Multi Theft Auto: Wiki - User contributions [en]

SetJetpackWeaponEnabled

2024-09-12T11:39:58Z

Dragon: various edits to correct information and to put formatting more in line with similar pages

__NOTOC__
{{Server function}}
This function sets a weapon usable while using the Jetpack.
{{Note|colt 45, sawed-off, tec-9 and uzi are always enabled for the Jetpack and are not affected by this function.}}
==Syntax==
<syntaxhighlight lang="lua">bool setJetpackWeaponEnabled ( int weaponID/string weaponName, bool enabled )</syntaxhighlight>

===Required Arguments===
*'''weaponID/weaponName:''' The ID or weapon name that's being set usable on a Jetpack. Names can be: (Case is ignored)
{{All Weapon Types}}
*'''enabled:''' A [[boolean]] representing whether the weapon is enabled or disabled.

===Returns===
Returns true if successful, or false if invalid arguments are passed.

==Example==
This example enables the M4 to be fired while using a jetpack and announces it in the chat.
<syntaxhighlight lang="lua">addEventHandler("onResourceStart",resourceRoot,function()
if setJetpackWeaponEnabled("31",true) then
outputChatBox(getWeaponNameFromID(31).." is now enabled for jetpacks!")
end
end)</syntaxhighlight>

This example enables the M4, sniper rifle and country rifle to be fired while using a jetpack and announces it in the chat.
<syntaxhighlight lang="lua">
local weapons = {
31,
34,
33,
}

addEventHandler("onResourceStart",resourceRoot,function()
for i,v in ipairs(weapons) do
if setJetpackWeaponEnabled(v,true) then
outputChatBox(getWeaponNameFromID(v).." is now enabled for jetpacks!")
end
end
end
)</syntaxhighlight>

==Requirements==
{{Requirements|1.3.1|n/a|}}
==See Also==
{{World_functions|server}}

Template:Shared utility functions

2024-09-05T06:55:25Z

Dragon: added isTimerPaused and setTimerPaused

<ul>
<li>[[addDebugHook]]</li>
<li>[[base64Decode]]</li>
<li>[[base64Encode]]</li>
<li>[[debugSleep]]</li>
<li>[[decodeString]]</li>
<li>[[encodeString]]</li>
<li>[[fromJSON]]</li>

{{Added feature/item|1.6.0|1.5.9|21055|
<li>[[generateKeyPair]]</li>
}}
<li>[[getColorFromString]]</li>
<li>[[getDevelopmentMode]]</li>
<li>[[getDistanceBetweenPoints2D]]</li>
<li>[[getDistanceBetweenPoints3D]]</li>
<li>[[getEasingValue]]</li>
<li>[[getNetworkStats]]</li>
<li>[[getNetworkUsageData]]</li>
<li>[[getPerformanceStats]]</li>
<li>[[getRealTime]]</li>
<li>[[getTickCount]]</li>
<li>[[getTimerDetails]]</li>
<li>[[getTimers]]</li>
<li>[[getFPSLimit]]</li>
<li>[[getUserdataType]]</li>
<li>[[getVersion]]</li>
<li>[[gettok]]</li>
{{Added feature/item|1.5.9|1.5.8|20788|
<li>[[isTransferBoxVisible]]</li>
<li>[[setTransferBoxVisible]]</li>
}}
<li>[[hash]]</li>
<li>[[inspect]]</li>
<li>[[interpolateBetween]]</li>
<li>[[iprint]]</li>
<li>[[isOOPEnabled]]</li>
<li>[[isTimer]]</li>
{{New items|3.0161|1.6.0|
<li>[[isTimerPaused]]</li>
<li>[[setTimerPaused]]</li>
}}
<li>[[killTimer]]</li>
<li>[[md5]]</li>
<li>[[passwordHash]]</li>
<li>[[passwordVerify]]</li>
<li>[[pregFind]]</li>
<li>[[pregMatch]]</li>
<li>[[pregReplace]]</li>
<li>[[removeDebugHook]]</li>
<li>[[resetTimer]]</li>
<li>[[setDevelopmentMode]]</li>
<li>[[setFPSLimit]]</li>
<li>[[setTimer]]</li>
<li>[[ref]]</li>
<li>[[deref]]</li>
<li>[[sha256]]</li>
<li>[[split]]</li>
<li>[[teaDecode]]</li>
<li>[[teaEncode]]</li>
<li>[[toJSON]]</li>
<li>[[tocolor]]</li>
<li>[[getProcessMemoryStats]]</li>
<li>[[utfChar]]</li>
<li>[[utfCode]]</li>
<li>[[utfLen]]</li>
<li>[[utfSeek]]</li>
<li>[[utfSub]]</li>
</ul>

{{Bit_functions}}

<noinclude>[[Category:Functions templates]]</noinclude>

SetTimerPaused

2024-09-05T06:53:56Z

Dragon: Created page with "{{Server client function}} __NOTOC__ {{New feature/item|3.0161|1.6.0|22701| This function allows you to pause existing running timers and resume existing paused ti..."

{{Server client function}}
__NOTOC__
{{New feature/item|3.0161|1.6.0|22701|
This function allows you to pause existing running timers and resume existing paused timers.
}}

==Syntax==
<syntaxhighlight lang="lua">
bool setTimerPaused ( timer theTimer, bool paused )
</syntaxhighlight>
{{OOP||[[timer]]:paused||}}
===Required Arguments===
*'''theTimer:''' The [[timer]] you wish to pause or resume.
*'''paused:''' Whether you want to pause (''true'') or resume (''false'') the [[timer]].

===Returns===
Returns ''true'' if the timer was successfully paused or resumed, ''false'' if no such timer existed.

==Example==

This example pauses all current timers from this resource.
<syntaxhighlight lang="lua">
-- Get a table of all current timers from this resource
local timers = getTimers ( )
-- Loop through the table of timers
for timerIndex, timerValue in ipairs( timers ) do
-- pause each timer
setTimerPaused ( timerValue, true )
end
</syntaxhighlight>

==See Also==
{{Utility functions}}

IsTimerPaused

2024-09-05T06:53:40Z

Dragon: Created page with {{Server client function}} __NOTOC__ {{New feature/item|3.0161|1.6.0|22701| This function allows you to check whether a timer is paused. }} ==Syntax== <syntaxhighlight lang="lua"> bool isTimerPa...

{{Server client function}}
__NOTOC__
{{New feature/item|3.0161|1.6.0|22701|
This function allows you to check whether a timer is paused.
}}

==Syntax==
<syntaxhighlight lang="lua">
bool isTimerPaused ( timer theTimer )
</syntaxhighlight>
{{OOP||[[timer]]:paused||}}
===Required Arguments===
*'''theTimer:''' The [[timer]] you wish to check.

===Returns===
Returns ''true'' if the timer is currently paused, ''false'' if not or if no such timer existed.

==Example==

This example pauses all currently running timers and resumes all currently paused timers from this resource.
<syntaxhighlight lang="lua">
-- Get a table of all current timers from this resource
local timers = getTimers ( )
-- Loop through the table of timers
for timerIndex, timerValue in ipairs( timers ) do
-- check if each timer is currently paused
local isPaused = isTimerPaused( timerValue )
-- pause or resume each timer based on its current state
setTimerPaused ( timerValue, not isPaused )
end
</syntaxhighlight>

==See Also==
{{Utility functions}}

Default resources

2024-07-08T05:50:26Z

Dragon: added links to gamemode pages

This page is related to the [https://github.com/multitheftauto/mtasa-resources mtasa-resources] project, the Default Lua resources that come with the Multi Theft Auto (MTA) multiplayer mod.

{{Note|This article is currently '''Work In Progress'''}}

== Download ==
These resources are available for '''download''' as a full ZIP archive on the '''Official Resources''' webpage at https://mirror-cdn.multitheftauto.com/mtasa/resources/. You may also obtain the files by downloading the GitHub Repository as a zip archive or by cloning it to your machine using Git.

== Resources ==
All resources described below can be found in the [https://github.com/multitheftauto/mtasa-resources mtasa-resources official GitHub repository]. To learn about a resource's history and recent changes, view the '''Git Commit History''' available online.

=== [[File:Preferences-system.svg|48px]] Administration ===

===== [[admin]] =====
MTA's default admin panel. Originally created by lil_Toady.

===== admin2 =====
A general overhaul to MTA's default admin panel which is currently in development and meant to eventually replace the original admin resource.

===== ip2c =====
Utility resource to find the country associated with a certain IP-address range.

===== runcode =====
Runcode allows the user to quickly execute code via the use of an ingame command. Use /run [your code] for server-side or /crun [your code] for client-side code execution. Typically used for testing on development servers, not recommended for production level servers.

=== [[File:Preferences-desktop-wallpaper.svg|48px]] Map Editor ===

===== [[editor]] =====
MTA's default map editor system, allowing you to create maps for gamemodes.

===== [[edf]] =====
EDF stands for Editor Definition File. This resource is the core functionality behind .edf files.

=== [[File:Input-gaming.svg|48px]] Gamemodes ===

===== [[resource:assault|assault]] =====
In assault one team has to fulfill certain tasks within a time limit while the other team has to prevent their opponents from completing them.

===== briefcaserace =====
In briefcase race multiple teams compete to deliver briefcases to their destination.

===== [[Resource:CTF|ctf]] =====
In capture the flag two or more teams compete to steal and capture the flags of the opposing teams.

===== ctv =====
In capture the vehicle two or more teams compete to deliver vehicles to their home base before the opponents.

===== deathmatch =====
Deathmatch is a free-for-all gamemode where the goal is to reach a certain frag limit before anyone else.

===== fallout =====
In fallout players compete to stay on top of falling platforms for as long as possible.

===== hay =====
In hay players attempt reach the top of a tall tower made from moving hay bales.

===== play =====
MTA's default freeroam gamemode. It will spawn players around certain areas all over San Andreas and spawn in vehicles for them to explore the world with.

===== [[resource:race|race]] =====
MTA's race gamemode features both checkpoint races and last-man-standing style destruction derbies. Originally created by arc_ with lots of improvements from ccw.

===== [[Resource:Stealth|stealth]] =====
The stealth gamemode features noise and stealth mechanics as well as many gadgets players can choose from. Two teams compete to be the last one standing. Originally created by slothman and talidan.

===== tdm =====
A basic team deathmatch mode where two teams compete to reach a given frag limit before the other.

===== tdma =====
Team death match arena is another team death match gamemode. It functions similarly to 'tdm' but is usually played on smaller, more concealed maps with spawn points establishing a clear frontline separating the teams.

=== [[File:Input-gaming.svg|48px]] Gameplay ===

===== deathpickups =====
This resource will spawn weapon pickups near player corpses after they died.

===== defaultstats =====
While running, this resource will make sure to give players maximum stats for stamina, weapon skills and more.

===== freeroam =====
Freeroam provides players with a simple to use GUI window to do simple things like teleport, spawn vehicles or weapons, select a skin or play animations. It's used by the 'play'-gamemode.

===== gps =====
GPS is able to calculate and display the quickest road path between two points on the map. Use /path2 [x] [y] [z] with your desired destination coordinates to receive directions on your mini-map.

===== headshot =====
While this resource is running a single shot to a player's head will result in an instant kill.

===== [[hedit]] =====
Powerful in-game handling editor to adjust various vehicle handling properties in real-time.

===== [[Resource:Realdriveby|realdriveby]] =====
Enables advanced drive-bys with more weapons and configurable restrictions. Originally created by talidan.

===== reload =====
Enables players to reload their current weapon with a configurable (default 'r') key.

===== sfxbrowser =====
GUI browser to find and play sound effects from GTA:SA's sound banks. After starting the resource use /sfxbrowser to open.

=== [[File:Preferences-system-windows.svg|48px]] Managers ===

===== [[helpmanager]] =====
A GUI-interface meant to provide a central location for other resources to provide helpful insight on how to use them.

===== [[Resource:mapcycler|mapcycler]] =====
Enables servers to cycle between select lists of maps and gamemodes automatically.

===== [[votemanager]] =====
A resource to provide servers with the ability to start and process votes like mapvotes, kickvotes and more.

== Development ==
The [https://github.com/multitheftauto/mtasa-resources mtasa-resources] project is open source. Contributions can be done in various ways: not only with code, but also with documentation and bug reporting, for example.

===== Contributing =====
Everyone is welcome to participate in improving the resource pack. Read more about the development process here: [[Default resources - Contributing]]

[[Category: Development]]

Default resources

2024-07-07T17:24:35Z

Dragon: added ip2c; added runcode; added gamemodes

This page is related to the [https://github.com/multitheftauto/mtasa-resources mtasa-resources] project, the Default Lua resources that come with the Multi Theft Auto (MTA) multiplayer mod.

{{Note|This article is currently '''Work In Progress'''}}

== Download ==
These resources are available for '''download''' as a full ZIP archive on the '''Official Resources''' webpage at https://mirror-cdn.multitheftauto.com/mtasa/resources/. You may also obtain the files by downloading the GitHub Repository as a zip archive or by cloning it to your machine using Git.

== Resources ==
All resources described below can be found in the [https://github.com/multitheftauto/mtasa-resources mtasa-resources official GitHub repository]. To learn about a resource's history and recent changes, view the '''Git Commit History''' available online.

=== [[File:Preferences-system.svg|48px]] Administration ===

===== [[admin]] =====
MTA's default admin panel. Originally created by lil_Toady.

===== admin2 =====
A general overhaul to MTA's default admin panel which is currently in development and meant to eventually replace the original admin resource.

===== ip2c =====
Utility resource to find the country associated with a certain IP-address range.

===== runcode =====
Runcode allows the user to quickly execute code via the use of an ingame command. Use /run [your code] for server-side or /crun [your code] for client-side code execution. Typically used for testing on development servers, not recommended for production level servers.

=== [[File:Preferences-desktop-wallpaper.svg|48px]] Map Editor ===

===== [[editor]] =====
MTA's default map editor system, allowing you to create maps for gamemodes.

===== [[edf]] =====
EDF stands for Editor Definition File. This resource is the core functionality behind .edf files.

=== [[File:Input-gaming.svg|48px]] Gamemodes ===

===== assault =====
In assault one team has to fulfill certain tasks within a time limit while the other team has to prevent their opponents from completing them.

===== briefcaserace =====
In briefcase race multiple teams compete to deliver briefcases to their destination.

===== ctf =====
In capture the flag two or more teams compete to steal and capture the flags of the opposing teams.

===== ctv =====
In capture the vehicle two or more teams compete to deliver vehicles to their home base before the opponents.

===== deathmatch =====
Deathmatch is a free-for-all gamemode where the goal is to reach a certain frag limit before anyone else.

===== fallout =====
In fallout players compete to stay on top of falling platforms for as long as possible.

===== hay =====
In hay players attempt reach the top of a tall tower made from moving hay bales.

===== play =====
MTA's default freeroam gamemode. It will spawn players around certain areas all over San Andreas and spawn in vehicles for them to explore the world with.

===== race =====
MTA's race gamemode features both checkpoint races and last-man-standing style destruction derbies. Originally created by arc_ with lots of improvements from ccw.

===== stealth =====
The stealth gamemode features noise and stealth mechanics as well as many gadgets players can choose from. Two teams compete to be the last one standing. Originally created by slothman and talidan.

===== tdm =====
A basic team deathmatch mode where two teams compete to reach a given frag limit before the other.

===== tdma =====
Team death match arena is another team death match gamemode. It functions similarly to 'tdm' but is usually played on smaller, more concealed maps with spawn points establishing a clear frontline separating the teams.

=== [[File:Input-gaming.svg|48px]] Gameplay ===

===== deathpickups =====
This resource will spawn weapon pickups near player corpses after they died.

===== defaultstats =====
While running, this resource will make sure to give players maximum stats for stamina, weapon skills and more.

===== freeroam =====
Freeroam provides players with a simple to use GUI window to do simple things like teleport, spawn vehicles or weapons, select a skin or play animations. It's used by the 'play'-gamemode.

===== gps =====
GPS is able to calculate and display the quickest road path between two points on the map. Use /path2 [x] [y] [z] with your desired destination coordinates to receive directions on your mini-map.

===== headshot =====
While this resource is running a single shot to a player's head will result in an instant kill.

===== [[hedit]] =====
Powerful in-game handling editor to adjust various vehicle handling properties in real-time.

===== [[Resource:Realdriveby|realdriveby]] =====
Enables advanced drive-bys with more weapons and configurable restrictions. Originally created by talidan.

===== reload =====
Enables players to reload their current weapon with a configurable (default 'r') key.

===== sfxbrowser =====
GUI browser to find and play sound effects from GTA:SA's sound banks. After starting the resource use /sfxbrowser to open.

=== [[File:Preferences-system-windows.svg|48px]] Managers ===

===== [[helpmanager]] =====
A GUI-interface meant to provide a central location for other resources to provide helpful insight on how to use them.

===== [[Resource:mapcycler|mapcycler]] =====
Enables servers to cycle between select lists of maps and gamemodes automatically.

===== [[votemanager]] =====
A resource to provide servers with the ability to start and process votes like mapvotes, kickvotes and more.

== Development ==
The [https://github.com/multitheftauto/mtasa-resources mtasa-resources] project is open source. Contributions can be done in various ways: not only with code, but also with documentation and bug reporting, for example.

===== Contributing =====
Everyone is welcome to participate in improving the resource pack. Read more about the development process here: [[Default resources - Contributing]]

[[Category: Development]]

Default resources

2024-07-04T08:07:01Z

Dragon: alphabetical order restored

Work in Progress - This page is related to the [https://github.com/multitheftauto/mtasa-resources mtasa-resources] project, the Default Lua resources that come with the Multi Theft Auto (MTA) multiplayer mod.

===== [[admin]] =====
MTA's default admin panel. Originally created by lil_Toady.

===== admin2 =====
A general overhaul to MTA's default admin panel which is currently in development and meant to eventually replace the original admin resource.

===== deathpickups =====
This resource will spawn weapon pickups near player corpses after they died.

===== defaultstats =====
While running, this resource will make sure to give players maximum stats for stamina, weapon skills and more.

===== freeroam =====
MTA's default freeroam gamemode. Will spawn players around certain areas all over San Andreas and spawn in vehicles for them to explore the world with.

===== gps =====
GPS is able to calculate and display the quickest road path between two points on the map. Use /path2 [x] [y] [z] with your desired destination coordinates to receive directions on your mini-map.

===== headshot =====
While this resource is running a single shot to a player's head will result in an instant kill.

===== [[hedit]] =====
Powerful in-game handling editor to adjust various vehicle handling properties in real-time.

===== [[helpmanager]] =====
A GUI-interface meant to provide a central location for other resources to provide helpful insight on how to use them.

===== [[Resource:mapcycler|mapcycler]] =====
Enables servers to cycle between select lists of maps and gamemodes automatically.

===== [[Resource:Realdriveby|realdriveby]] =====
Enables advanced drive-bys with more weapons and configurable restrictions. Originally created by talidan.

===== reload =====
Enables players to reload their current weapon with a configurable (default 'r') key.

===== sfxbrowser =====
GUI browser to find and play sound effects from GTA:SA's sound banks. After starting the resource use /sfxbrowser to open.

===== [[votemanager]] =====
A resource to provide servers with the ability to start and process votes like mapvotes, kickvotes and more.

<h1>Development</h1>
Everyone is welcome to participate in improving the resource pack. Read more about the development process here: [[Default resources - Contributing]]

[[Category: Development]]

Default resources

2024-07-04T03:33:29Z

Dragon: added a couple initial entries to spark discussion on formatting, content and phrasing

Work in Progress - This page is related to the [https://github.com/multitheftauto/mtasa-resources mtasa-resources] project, the Default Lua resources that come with the Multi Theft Auto (MTA) multiplayer mod.

===== [[admin]] =====
MTA's default admin panel. Originally created by lil_Toady.

===== admin2 =====
A general overhaul to MTA's default admin panel which is currently in development and meant to eventually replace the original admin resource.

===== deathpickups =====
This resource will spawn weapon pickups near player corpses after they died.

===== defaultstats =====
While running, this resource will make sure to give players maximum stats for stamina, weapon skills and more.

===== freeroam =====
MTA's default freeroam gamemode. Will spawn players around certain areas all over San Andreas and spawn in vehicles for them to explore the world with.

===== gps =====
GPS is able to calculate and display the quickest road path between two points on the map. Use /path2 [x] [y] [z] with your desired destination coordinates to receive directions on your mini-map.

===== headshot =====
While this resource is running a single shot to a player's head will result in an instant kill.

===== [[hedit]] =====
Powerful in-game handling editor to adjust various vehicle handling properties in real-time.

===== [[helpmanager]] =====
A GUI-interface meant to provide a central location for other resources to provide helpful insight on how to use them.

===== [[Resource:mapcycler|mapcycler]] =====
Enables servers to cycle between select lists of maps and gamemodes automatically.

===== reload =====
Enables players to reload their current weapon with a configurable (default 'r') key.

===== [[Resource:Realdriveby|realdriveby]] =====
Enables advanced drive-bys with more weapons and configurable restrictions. Originally created by talidan.

===== sfxbrowser =====
GUI browser to find and play sound effects from GTA:SA's sound banks. After starting the resource use /sfxbrowser to open.

===== [[votemanager]] =====
A resource to provide servers with the ability to start and process votes like mapvotes, kickvotes and more.

<h1>Development</h1>
Everyone is welcome to participate in improving the resource pack. Read more about the development process here: [[Default resources - Contributing]]

[[Category: Development]]

Talk:OnClientPlayerWeaponFire

2024-04-25T03:45:10Z

Dragon: Created page with "Pending testing whether remote player's projectile weapons (rocket launcher, grenades, etc.) or the camera trigger this event. Local player's definitely do --~~~~"

Pending testing whether remote player's projectile weapons (rocket launcher, grenades, etc.) or the camera trigger this event. Local player's definitely do --[[User:Dragon|Dragon]] ([[User talk:Dragon|talk]]) 03:44, 25 April 2024 (UTC)

OnClientPlayerWeaponFire

2024-04-25T03:37:36Z

Dragon: corrected info to reflect that the local player's projectile weapons or the camera will indeed correctly trigger the event

{{Client event}}
__NOTOC__
This event is called when a player fires a weapon. This event does not trigger for melee weapons. Projectile weapons or the camera will only trigger the event if fired by the local player.
{{Note|This event is only triggered for players that are streamed in}}
{{Note|This does not trigger for any player's melee weapons or for remote player's projectile weapons or cameras}}
==Parameters==
<syntaxhighlight lang="lua">
int weapon, int ammo, int ammoInClip, float hitX, float hitY, float hitZ, element hitElement, float startX, float startY, float startZ
</syntaxhighlight>
*'''weapon''': an [[int]] representing [[weapons|weapon]] used for firing a shot.
*'''ammo''': an [[int]] amount of ammo left for this weapon type.
*'''ammoInClip''': an [[int]] amount of ammo left for this weapon type in clip.
*'''hitX''', '''hitY''', '''hitZ''': [[float]] world coordinates representing a hit point.
*'''hitElement''': an [[element]] which was hit by a shot.
{{New feature/item|3.0131|1.3.1|4311|
*'''startX''', '''startY''', '''startZ''': [[float]] world coordinates representing the start of the bullet. Note: This is not the gun muzzle.
}}

==Source==
The [[event system#Event source|source]] of this event is the streamed in [[player]] who fired the weapon.

==Example==
This example implements custom gunshot sounds.
<syntaxhighlight lang="lua">
function playGunfireSound(weaponID)
local muzzleX, muzzleY, muzzleZ = getPedWeaponMuzzlePosition(source)
local dim = getElementDimension(source)
local int = getElementInterior(source)
setAmbientSoundEnabled ("gunfire", false)

local weaponSounds = {
[22] = "sounds/weap/colt45.ogg",
[23] = "sounds/weap/silenced.ogg",
[24] = "sounds/weap/deagle.ogg",
[25] = "sounds/weap/shotgun.ogg",
[26] = "sounds/weap/sawed-off.ogg",
[27] = "sounds/weap/combat shotgun.ogg",
[28] = "sounds/weap/uzi.ogg",
[30] = "sounds/weap/ak-47.ogg",
[31] = "sounds/weap/m4.ogg",
[32] = "sounds/weap/tec9.ogg",
[34] = "sounds/weap/sniper.ogg",
}

if weaponSounds[weaponID] then
sound = playSound3D(weaponSounds[weaponID], muzzleX, muzzleY, muzzleZ)
setSoundMaxDistance(sound, 90)
setElementDimension(sound, dim)
setElementInterior(sound, int)
setSoundVolume(sound, 0.6)
end
end
addEventHandler("onClientPlayerWeaponFire", root, playGunfireSound)
</syntaxhighlight>

This example sends a warning to the local player if they shoot another player with a minigun.
<syntaxhighlight lang="lua">
--First, we create a function for the event handler to use.
function onClientPlayerWeaponFireFunc(weapon, ammo, ammoInClip, hitX, hitY, hitZ, hitElement )
if weapon == 38 and getElementType(hitElement)=="player" then -- If the player shoots with a minigun, and hits another player...
outputChatBox ( "Don't kill people with minigun, it's lame!", 255, 0, 0 ) -- We output a warning to him.
end
end
-- Add this as a handler so that the function will be triggered every time the local player fires.
addEventHandler ( "onClientPlayerWeaponFire", localPlayer, onClientPlayerWeaponFireFunc )
</syntaxhighlight>

This example makes the Shotgun fire explosive rounds.
<syntaxhighlight lang="lua">
function onClientPlayerWeaponFireFunc(weapon, ammo, ammoInClip, hitX, hitY, hitZ, hitElement)
if (weapon == 25) then -- If the player shoots with a shotgun
createExplosion(hitX, hitY, hitZ, 12, true, 0, true) -- Creates a tiny explosion where the bullet hit.
end
end
-- Add this as a handler so that the function will be triggered every time a player fires.
addEventHandler("onClientPlayerWeaponFire", root, onClientPlayerWeaponFireFunc)
</syntaxhighlight>

==See Also==
===Client player events===
{{Client_player_events}}
===Client event functions===
{{Client_event_functions}}

SetPedAimTarget

2023-09-21T14:26:58Z

Dragon: /* Example */ fixed a typo

__NOTOC__
{{Client function}}
This function allows you to set a ped's aim target to a specific point. If a ped is within a certain range defined by [[getPedTargetStart]] and [[getPedTargetEnd]] he will be targeted and shot.

''Note: If you wish to make a ped shoot you must use this in conjunction with an equipped weapon and [[setPedControlState]].''

==Syntax==
<syntaxhighlight lang="lua">
bool setPedAimTarget ( ped thePed, float x, float y, float z )
</syntaxhighlight>

===Required Arguments===
*'''thePed:''' The ped whose target you want to set. Only peds and remote players will work; this function has no effect on the local player.
*'''x:''' The x coordinate of the aim target point.
*'''y:''' The y coordinate of the aim target point.
*'''z:''' The z coordinate of the aim target point.

===Returns===
Returns ''true'' if the function was successful, ''false'' otherwise.

==Example==
'''Example 1:''' This example creates a ped in the middle of the map and sets its aim target to point north-east.
<syntaxhighlight lang="lua">
function createPedAndsetHisAimTarget ()
local ped = createPed (0, 0, 0, 5 ) -- create a ped, who looks like cj, in the middle of the map
setPedAimTarget ( ped, 10, 10, 5 ) -- set the ped's target to a point in North-East
end
</syntaxhighlight>

'''Example 2:''' This example creates a ped at grove street that will shoot at anything that enters a certain marker.
<syntaxhighlight lang="lua">
local cj = createPed(0, 2498.5, -1684.0, 13.5, 20) -- create a ped at cjs house in grove street and give it an ak
givePedWeapon(cj, 30, 3000, true)

local marker = createMarker(2493.0, -1669.0, 13.5, "checkpoint", 3, 255, 0, 0, 128) -- create a marker and get its associated colshape for later use
local colshape = getElementColShape(marker)

function renderHandler()
local intruder = getElementsWithinColShape(colshape)[2] -- get the second element found within the colshape, because the first one will normally be the marker itself
if intruder then
local x,y,z = getElementPosition(intruder) -- if an intruder exists, get its position and have the cj ped fire at it
setPedAimTarget(cj, x, y, z)
setPedControlState(cj, "fire", true)
else
setPedControlState(cj, "fire", false) -- otherwise stop shooting
end
end
addEventHandler("onClientRender", getRootElement(), renderHandler) -- add an event handler to go through the target acquisition procedure every frame
</syntaxhighlight>

==See Also==
{{Client ped functions}}

SetPedAimTarget

2023-09-21T14:24:27Z

Dragon: /* Example */ Added an additional example

__NOTOC__
{{Client function}}
This function allows you to set a ped's aim target to a specific point. If a ped is within a certain range defined by [[getPedTargetStart]] and [[getPedTargetEnd]] he will be targeted and shot.

''Note: If you wish to make a ped shoot you must use this in conjunction with an equipped weapon and [[setPedControlState]].''

==Syntax==
<syntaxhighlight lang="lua">
bool setPedAimTarget ( ped thePed, float x, float y, float z )
</syntaxhighlight>

===Required Arguments===
*'''thePed:''' The ped whose target you want to set. Only peds and remote players will work; this function has no effect on the local player.
*'''x:''' The x coordinate of the aim target point.
*'''y:''' The y coordinate of the aim target point.
*'''z:''' The z coordinate of the aim target point.

===Returns===
Returns ''true'' if the function was successful, ''false'' otherwise.

==Example==
'''Example 1:''' This example creates a ped in the middle of the map and sets its aim target to be point north-east.
<syntaxhighlight lang="lua">
function createPedAndsetHisAimTarget ()
local ped = createPed (0, 0, 0, 5 ) -- create a ped, who looks like cj, in the middle of the map
setPedAimTarget ( ped, 10, 10, 5 ) -- set the ped's target to a point in North-East
end
</syntaxhighlight>

'''Example 2:''' This example creates a ped at grove street that will shoot at anything that enters a certain marker.
<syntaxhighlight lang="lua">
local cj = createPed(0, 2498.5, -1684.0, 13.5, 20) -- create a ped at cjs house in grove street and give it an ak
givePedWeapon(cj, 30, 3000, true)

local marker = createMarker(2493.0, -1669.0, 13.5, "checkpoint", 3, 255, 0, 0, 128) -- create a marker and get its associated colshape for later use
local colshape = getElementColShape(marker)

function renderHandler()
local intruder = getElementsWithinColShape(colshape)[2] -- get the second element found within the colshape, because the first one will normally be the marker itself
if intruder then
local x,y,z = getElementPosition(intruder) -- if an intruder exists, get its position and have the cj ped fire at it
setPedAimTarget(cj, x, y, z)
setPedControlState(cj, "fire", true)
else
setPedControlState(cj, "fire", false) -- otherwise stop shooting
end
end
addEventHandler("onClientRender", getRootElement(), renderHandler) -- add an event handler to go through the target acquisition prodecure every frame
</syntaxhighlight>

==See Also==
{{Client ped functions}}

User talk:Quiret

2023-06-15T19:02:15Z

Dragon:

Hi, thanks! The [https://wiki.multitheftauto.com/wiki/Where_to_buy_GTASA where to buy page] definitely needed some changes, as its primary purpose (telling people how they can legitimately obtain a compatible copy) got a little lost as time progressed and the game became harder to obtain. The whole Definitive Edition situation made things so much worse. After finally receiving confirmation recently that 'The Trilogy', as I assumed, contains a compatible version I had all the information I needed to reorganize everything and with the help of some feedback from the Developer Discord this is what I came up with. It should hopefully make it very clear to anyone interested in getting into MTA:SA what they can do if they want a legitimate compatible copy. No, I didn't consult any AI text generation for the content, the only AI involvement was me asking ChatGPT about certain keywords for styling, which in the end I used to have the extra little bit of separation between the different 'Products' on the table. Thanks again for your nice comment and your continued efforts on the wiki. --[[User:Dragon|Dragon]] ([[User talk:Dragon|talk]]) 19:01, 15 June 2023 (UTC)

User talk:Quiret

2023-06-15T19:01:54Z

Dragon: ty

Hi, thanks! The [https://wiki.multitheftauto.com/wiki/Where_to_buy_GTASA there to buy page] definitely needed some changes, as its primary purpose (telling people how they can legitimately obtain a compatible copy) got a little lost as time progressed and the game became harder to obtain. The whole Definitive Edition situation made things so much worse. After finally receiving confirmation recently that 'The Trilogy', as I assumed, contains a compatible version I had all the information I needed to reorganize everything and with the help of some feedback from the Developer Discord this is what I came up with. It should hopefully make it very clear to anyone interested in getting into MTA:SA what they can do if they want a legitimate compatible copy. No, I didn't consult any AI text generation for the content, the only AI involvement was me asking ChatGPT about certain keywords for styling, which in the end I used to have the extra little bit of separation between the different 'Products' on the table. Thanks again for your nice comment and your continued efforts on the wiki. --[[User:Dragon|Dragon]] ([[User talk:Dragon|talk]]) 19:01, 15 June 2023 (UTC)

Where to buy GTASA

2023-06-13T17:41:43Z

Dragon: Updated and re-ordered table; added purchase availability; added non-compatibility-warning about The Definitive Edition; added note about Steam or RGL keys from key-resellers; updated wording to be clear and consistent across the page

This page outlines general version compatibility for Grand Theft Auto: San Andreas with MTA:SA as well as where they can be purchased.

=== Compatibility ===

If a version of Grand Theft Auto: San Andreas marked below as compatible is not working, please try reinstalling MTA:SA. If that doesn't work, follow [https://forum.mtasa.com/topic/11757-patching-your-101-or-200-version-of-gta_saexe/ these instructions]. If that still doesn't work, then please contact us on [https://forum.mtasa.com/forum/83-client/ on the forums], or join the [https://mtasa.com/discord MTA Discord #help-support channel].
{{Important Note|Grand Theft Auto: San Andreas as part of '''Grand Theft Auto: The Trilogy – The Definitive Edition''' ''(2021)'' is an entirely new release of the game. This version is '''not compatible''' with MTA:SA.}}

=== Obtaining compatible & used copies ===

Officially, the only way to purchase a compatible copy of Grand Theft Auto: San Andreas from Rockstar Games and Take-Two is through the purchase of the classic collection [https://store.rockstargames.com/en/game/buy-grand-theft-auto-the-trilogy '''Grand Theft Auto: The Trilogy''' ''(2005)'' on the Rockstar Store]. The only other two options are either getting a used physical copy through flea-markets and private resellers or by buying a key for a compatible digital version from a key reseller. A prominent example in the EU for buying a used physical copy is [https://ebay.com ebay.com]. By typing in "gta san andreas pc" into the search field you can find plenty of people that still sell the compatible game. Be careful though as buying from untrustworthy resellers such as unknown non-business people does pose risks (for example fake or broken copies). To find a digital key-reseller, using a search engine to find "Grand Theft Auto: San Andreas key" or similar should yield plenty results. Evaluate which sources are trustworthy and check the key will work in your region before you consider a purchase.

{| class="wikitable" style="width: 900px; text-align: center; table-layout: fixed;"
|-
!Product
!Retailer
!Works with MTA:SA?
!Available for purchase?
!Notes
|-
| rowspan="2" |Grand Theft Auto: The Trilogy ''(2005)''
|[https://store.rockstargames.com/en/game/buy-grand-theft-auto-the-trilogy Rockstar Store]
|{{Yes}}
|{{Yes|[https://store.rockstargames.com/en/game/buy-grand-theft-auto-the-trilogy Yes]}}
| rowspan="2" |This is the 2005 collection of the '''3 original classic GTA games'''. It's currently the only version which is both '''compatible''' and '''available for purchase'''.
|-
|Steam
|{{Yes}}
|{{NoAsterisk}}
|-
| colspan="5" style="background: black; height: 1px; padding: 0px;"|
|-
| rowspan="3" |Grand Theft Auto: San Andreas
(Digital copy)
|Rockstar Store
|{{Yes}}
|{{NoAsterisk}}
| rowspan="2" |MTA:SA installer will make this compatible for you (make sure to install the latest version of MTA:SA '''after''' installing the digital GTA version), but without modifying original game files.
|-
|[https://store.steampowered.com/app/12120/Grand_Theft_Auto_San_Andreas/ Steam]
|{{Yes}}
|{{NoAsterisk}}
|-
|[https://www.microsoft.com/en-us/p/grand-theft-auto-san-andreas/9wzdncrfj1zn Windows App Store]
|{{No}}
|{{No}}
|This is a mobile/Xbox "remastered" version of the game ported to PC. '''Will never work with MTA:SA.'''
|-
| colspan="5" style="background: black; height: 1px; padding: 0px;"|
|-
|Grand Theft Auto: San Andreas
(Used physical copy)
|Amazon / Ebay / etc.
[http://www.amazon.com/Grand-Theft-Auto-Andreas-Download/dp/B006YVXGJQ link 1] [https://www.amazon.de/Grand-Theft-Auto-Andreas-DVD-ROM/dp/B00076YSDM/ref=sr_1_1 link 2] [https://www.amazon.com/-/de/dp/B001DUG0NC/ref=sr_1_14 link 3]
|{{Partial|Unconfirmed (Standard)}}
|{{Partial|Depending}}
|For the '''Standard''' edition of the game, if MTA:SA is incompatible, visit [https://forum.mtasa.com/topic/11757-patching-your-101-or-200-version-of-gta_saexe/ this topic] and follow the instructions, or try obtaining a GTA:SA 1.00 No CD - any HOODLUM release will function correctly.
|}

<nowiki>*</nowiki>Still available through key resellers. Only consider purchasing from reputable sources and check for region restrictions.

[[hu:Where to buy GTASA]]
[[es:Dónde comprar GTA: SA]]
[[pl:Where to buy GTASA]]
[[ru:Where to buy GTASA]]
[[uk:Where to buy GTASA]]
[[tr:GTA:SA Nerden Alınır]]
[[zh-cn:在那里可以购买GTASA]]
[[ro:Where to buy GTASA]]

Template:NoAsterisk

2023-06-13T16:53:30Z

Dragon: Created new wiki table template

<noinclude>{| class="wikitable"
|-
|</noinclude>style="background: SandyBrown; color: black; vertical-align: middle; text-align: {{{align|center}}}; {{{style|}}}"|{{{1|No*}}}<noinclude>
|}
</noinclude>

DxDrawMaterialPrimitive3D

2023-04-02T19:25:13Z

Dragon: /* Example */ Added an example

__NOTOC__
{{Client function}}
This function draws a 3D primitive shape with material applied to it in the 3D world - rendered for one frame. This should be used in conjunction with [[onClientRender]] in order to display continuously.
If image file is used, it should ideally have dimensions that are a power of two, to prevent possible blurring.
Power of two: 2px, 4px, 8px, 16px, 32px, 64px, 128px, 256px, 512px, 1024px...

==Syntax==
<syntaxhighlight lang="lua">
bool dxDrawMaterialPrimitive3D ( primitiveType pType, mixed material, bool postGUI, table vertice1 [, table vertice2, ...] )
</syntaxhighlight>

===Required Arguments===
* '''pType:''' Type of primitive to be drawn.
* '''image:''' Either a [[material]] element or a [[filepath]] of the image which is going to be drawn. (.dds images are also supported). Image files should ideally have dimensions that are a power of two, to prevent possible blurring. Use a texture created with [[dxCreateTexture]] to '''speed up drawing'''.
* '''postGUI:''' A bool representing whether the line should be drawn on top of or behind any ingame GUI (rendered by CEGUI).
* '''vertices:''' Tables representing each primitive vertice, required amount of them is determined by primitive type.

==Allowed types==
[[Image:MTAsa_primitives.png|thumb|240px|Available primitive types.]]
More info on primitives may be found on [https://msdn.microsoft.com/en-us/library/windows/desktop/bb147291(v=vs.85).aspx this MSDN site]
* '''pointlist:''' Renders the vertices as a collection of isolated points.
* '''linelist:''' Renders the vertices as a list of isolated straight line segments.
* '''linestrip:''' Renders the vertices as a single polyline.
* '''trianglelist:''' Renders the specified vertices as a sequence of isolated triangles. Each group of three vertices defines a separate triangle.
* '''trianglestrip:''' Renders the vertices as a triangle strip.
* '''trianglefan:''' Renders the vertices as a triangle fan.

==Vertices format==
* '''posX:''' An float representing the X position of the vertice in the GTA world.
* '''posY:''' An float representing the Y position of the vertice in the GTA world.
* '''posZ:''' An float representing the Z position of the vertice in the GTA world.
* '''color (optional):''' An integer of the hex color, produced using [[tocolor]] or 0xAARRGGBB (AA = alpha, RR = red, GG = green, BB = blue). If it's not specified, white color is used.
* '''u:''' An float representing the relative X coordinate of the top left corner of the material which should be drawn from image
* '''v:''' An float representing the relative Y coordinate of the top left corner of the material which should be drawn from image

===Returns===
Returns a ''true'' if the operation was successful, ''false'' otherwise.

==Remarks==
When a 3D draw call is issued by any such material MTA function then the principle to [https://github.com/multitheftauto/mtasa-blue/blob/16769b8d1c94e2b9fe6323dcba46d1305f87a190/Client/core/Graphics/CMaterialPrimitive3DBatcher.cpp#L42 push it directly to the 3D adapter] does apply. To achieve this there is '''no software-side 3D clipping mathematics''' being performed. This way the vertex data is always being pushed to the vertex shader, leaving the entire freedom to the developer on how to interpret this vertex data in the shader. For example, even though this function does imply an use in 3D world space, the vertex coordinates could be translated directly into Direct3D 9 screen space instead, effectively discarding any multiplication with the camera projection matrix. The mathematical model for translation into valid Direct3D 9 screen-space coordinates is described [https://docs.microsoft.com/en-us/windows/win32/direct3d9/viewports-and-clipping here]. Let's assume that you are drawing the rectangle on a classic sheet of paper with a mathematical 2D X,Y coordinate system.

[[File:D3d9_screen_space_transformation.png|frameless|center|Direct3D 9 screen-space transformation]]

To transform the coordinates you first have to flip the Y coordinate using negation and then apply the Direct3D 9 screen-space rasterization cross-hair by using the screen dimensions (sw, sh). Since linear shapes are being preserved across linear translations, you can simplify each vertex-based figure into it's set of vertices for the purpose shown above. By using this function in such a way it can perform all the operations in the same quality such as the simpler [[dxDrawMaterialPrimitive]] function.

==Example==
This example draws the picture with the file name 'test.png' on the ground of Grove Street and adds a /flip command to flip it. The 'test.png' file needs to be included in the [[meta.xml]] in order for this example to work.
<syntaxhighlight lang="lua">
local picture = "test.png"
local worldRenderPositions = { -- create a table with all the world positions

{ 2483, -1663, 12.4, 0, 0 }, -- top left
{ 2493, -1663, 12.4, 1, 0 }, -- top right
{ 2483, -1673, 12.4, 0, 1 }, -- bottom left
{ 2493, -1673, 12.4, 1, 1 }, -- bottom right

}

function renderPicture()
dxDrawMaterialPrimitive3D( "trianglestrip", picture, false, unpack(worldRenderPositions) ) -- use unpack() to separate the points
end
addEventHandler( "onClientRender", root, renderPicture )

function flipPicture()
for index, point in ipairs(worldRenderPositions) do
if point[4] == 1 then
point[4] = 0
else
point[4] = 1
end
if point[5] == 1 then
point[5] = 0
else
point[5] = 1
end
end
end
addCommandHandler( "flip", flipPicture )
</syntaxhighlight>

This function can be used to draw billboards in the game world. You have to [https://forum.mtasa.com/topic/133065-naruto-jutsus-help-me/?do=findComment&comment=1003073 understand the mathematical models about the human vision] to calculate the proper vertices.

==Requirements==
{{Requirements|n/a|1.5.7-9.19626|}}

==See Also==
{{Drawing_functions}}

[[hu:dxDrawMaterialPrimitive3D]]

PlaySFX

2023-03-11T06:05:47Z

Dragon: /* Example */ Added another example, showcasing the "radio" syntax.

__NOTOC__
{{Client function}}
{{New feature/item|3.0134|1.3.4|5731|
This function plays a sound from GTA's big sound containers.
}}

{{Note|There is a tool available which allows you to find bank and sound IDs easily: [[https://community.mtasa.com/index.php?p=resources&s=details&id=7549 sfxBrowser:Download]].}}
{{Warning|Many players use versions of GTA:SA (especially pirated versions) that have audio files full of zeros so that they can compresses better in their ''AUDIO\SFX\'' folder. (They lack any data)
In case of these invalid audio files, this function returns ''false''.

It also returns ''false'' when trying to play a track deleted in the recent GTA: SA Steam patches (and if the client is using a Steam GTA: SA copy).|true}}
{{Note|PlaySFX sounds are MTA driven sounds, so MTA volume affects the volume.}}

==Syntax==
<syntaxhighlight lang="lua">
element playSFX ( string containerName, int bankId, int soundId [, bool looped = false ] )
</syntaxhighlight>

===Required Arguments===
*'''containerName:''' The name of the audio container. Possible values are: "feet", "genrl", "pain_a", "script", "spc_ea", "spc_fa", "spc_ga", spc_na", "spc_pa"
*'''bankId:''' The audio bank id
*'''soundId:''' The sound id within the audio bank

===Optional Arguments===
*'''looped:''' A [[boolean]] representing whether the sound will be looped
==Returns==
Returns a [[sound]] element if the sound was successfully created, ''false'' otherwise.

{{New feature/item|3.0140|1.4|6443|
==Syntax 2==
<syntaxhighlight lang="lua">
element playSFX ( string "radio", string radioStation, int trackId [, bool looped = false ] )
</syntaxhighlight>

===Required Arguments===
*'''radio:''' The string "radio" (used to differentiate to the first syntax)
*'''radioStation:''' The radio station. Possible values are "Adverts", "Ambience", "Police", "Playback FM", "K-Rose", "K-DST", "Cutscene", "Beats", "Bounce FM", "SF-UR", "Radio Los Santos", "Radio X", "CSR 103.9", "K-Jah West", "Master Sounds 98.3", "WCTR".
*'''trackId :''' The radio track id within the radio station audio file

===Optional Arguments===
*'''looped:''' A [[boolean]] representing whether the sound will be looped
==Returns==
Returns a [[sound]] element if the sound was successfully created, ''false'' otherwise.
}}

==Example==
The following example plays a firealarm sound (looped).
<syntaxhighlight lang="lua">
if not playSFX("script", 7, 1, true) then
outputChatBox("You have to install some missing audio files to hear the sound")
end
</syntaxhighlight>

This example spawns Big Smoke in his Crack Palace and plays one of his screams followed by the mission accomplished sound when he's killed.
<syntaxhighlight lang="lua">
local bigsmoke = createPed(311,2550.53, -1284.81, 1060.98, 270)
setElementInterior(bigsmoke, 2)

function smokeDied()
playSFX("spc_na", 32, 34)
setTimer(playSFX, 1000, 1, "radio", "Beats", 9)
end
addEventHandler("onClientPedWasted", bigsmoke, smokeDied)
</syntaxhighlight>

==See Also==
{{Client_audio_functions}}

[[hu:playSFX]]
[[pt-br:playSFX]]

DxDrawPrimitive

2023-01-28T20:28:26Z

Dragon: /* Example */ added yet another example, hidden by default because it just expands on the previous one and is probably more suited towards advanced users. also fixed a comment in the previous example to be fully accurate

__NOTOC__
{{Client function}}
{{New feature/item|3.0157|1.5.6|14370|This function draws a 2D primitive shape across the screen - rendered for one frame. This should be used in conjunction with [[onClientRender]] in order to display continuously.}}

==Syntax==
<syntaxhighlight lang="lua">
bool dxDrawPrimitive ( string pType, bool postGUI, table vertice1 [, table vertice2, ...] )
</syntaxhighlight>

===Required Arguments===
* '''pType:''' Type of primitive to be drawn.
* '''postGUI:''' A bool representing whether the line should be drawn on top of or behind any ingame GUI (rendered by CEGUI).
* '''vertices:''' Tables representing each primitive vertice, required amount of them is determined by primitive type.

==Allowed types==
[[Image:MTAsa_primitives.png|thumb|240px|Available primitive types.]]
More info on primitives may be found on [https://msdn.microsoft.com/en-us/library/windows/desktop/bb147291(v=vs.85).aspx this MSDN site]
* '''pointlist:''' Renders the vertices as a collection of isolated points.
* '''linelist:''' Renders the vertices as a list of isolated straight line segments.
* '''linestrip:''' Renders the vertices as a single polyline.
* '''trianglelist:''' Renders the specified vertices as a sequence of isolated triangles. Each group of three vertices defines a separate triangle.
* '''trianglestrip:''' Renders the vertices as a triangle strip.
* '''trianglefan:''' Renders the vertices as a triangle fan.

==Vertices format==
* '''posX:''' An float representing the absolute X position of the vertice, represented by pixels on the screen.
* '''posY:''' An float representing the absolute Y position of the vertice, represented by pixels on the screen.
* '''color (optional):''' An integer of the hex color, produced using [[tocolor]] or 0xAARRGGBB (AA = alpha, RR = red, GG = green, BB = blue). If it's not specified, white color is used.

===Returns===
Returns a ''true'' if the operation was successful, ''false'' otherwise.

==Example==
<section name="Example 1" class="client" show="true">
This is a small example that creates trianglefan primitive with vertices in places that user clicks. It assigns every vertice random color.
<syntaxhighlight lang="lua">
local vertices = {}
function onClick(btn, state, x, y)
if btn ~= "left" then return end
if state ~= "up" then return end
local vertice = {x, y, tocolor(math.random(255), math.random(255), math.random(255))}
table.insert(vertices, vertice)
end
addEventHandler("onClientClick", root, onClick)

function draw()
dxDrawPrimitive("trianglefan", true, unpack(vertices))
end
addEventHandler("onClientPreRender", root, draw)
</syntaxhighlight>
</section>
<section name="Example 2" class="client" show="true">
This example draws one complete oscillation of a sine wave starting in the center of the players screen using a linestrip type primitive.
<syntaxhighlight lang="lua">
local screenSizeX,screenSizeY = guiGetScreenSize() -- save the current screen dimensions
local sinCoords = {}

function resStart() -- do all this once during "onClientResourceStart", rather than every frame
local range = math.pi * 2 -- to get 1 complete oscillation of the sine wave we need the range from 0 to 2pi
local resolution = 100 -- resolution in this example means in how many steps we draw the linestrip, higher resolution means smoother curve at the expense of longer computation time and higher memory usage
local scale = 50
for i=0,range,range/resolution do -- "loop through this [resolution] times, starting at 0 and ending at [range]"
local x = screenSizeX * 0.5 + i * scale -- start at the center of the screen and go from there
local y = screenSizeY * 0.5 - math.sin(i) * scale -- subtract rather than add because greater y value means lower on the screen, which is the opposite of what we're used to seeing in graphs
table.insert(sinCoords,{x,y})
end
end
addEventHandler("onClientResourceStart",getResourceRootElement(getThisResource()), resStart)

function exampleRender()
dxDrawPrimitive("linestrip",true,unpack(sinCoords)) -- render a linestrip type primitive with the coordinates we calculated earlier to draw our sine wave
end
addEventHandler("onClientRender",getRootElement(),exampleRender)
</syntaxhighlight>
</section>
<section name="Example 3" class="client" show="false">
Modifying the previous example, we can also use it to draw a "loading circle"-symbol similar to what some modern games like using to indicate loading or cloud saving in progress.
<syntaxhighlight lang="lua">
local screenSizeX,screenSizeY = guiGetScreenSize() -- save the current screen dimensions
local circleCoords = {}
local resolution = 100 -- resolution in this example means in how many steps we draw the linestrip, higher resolution means smoother curve at the expense of longer computation time and higher memory usage
local scale = 20
local maxSegmentPercentage = 0.75 -- this means the largest our line will get is 3/4 of the full circle
local startPointRevolution = 2000 -- one full revolution around the circle for our starting point after this amount of milliseconds passed
local endPointOscillation = 3000 -- one full oscillation of our endpoint after this amount of milliseconds passed

function resStart() -- do all this once during "onClientResourceStart", rather than every frame
local range = math.pi * 2 -- to complete a circle we need the range from 0 to 2pi
for i=0,range,range/resolution do -- "loop through this [resolution] times, starting at 0 and ending at [range]"
local x = screenSizeX * 0.5 + math.sin(i) * scale -- for a circle we get our x coordiante from sine and the y coordinate from cosine or vice versa
local y = screenSizeY * 0.5 - math.cos(i) * scale -- subtract will later result in a clockwise spin, add in a counter clockwise one
table.insert(circleCoords,{x,y})
end
end
addEventHandler("onClientResourceStart",getResourceRootElement(getThisResource()), resStart)

function exampleRender()
local tick = getTickCount() -- get the current time in milliseconds, then use it in a few clever ways to animate our circle
local firstPoint = math.ceil( ((tick/startPointRevolution) % 1)*resolution ) -- firstly dividing it and using %1 (modulo 1) to repeatedly get a slowly, linearly increasing value from 0 to 1. This is our starting point
local secondPoint = math.ceil( firstPoint + (math.sin(tick/endPointOscillation)) * resolution*maxSegmentPercentage ) -- secondly figuring out where we want our end point to be, using sine to get a pleasant looking pulse for the line growth

if firstPoint > secondPoint then -- because of how we calculate our end point, half the time it will be smaller than the start point. for unpack() to give us the range we want we need to provide the smaller value first
firstPoint, secondPoint = secondPoint, firstPoint
end

if secondPoint > resolution then -- sometimes we'll wrap around the origin point of our circle, those cases need to be taken care of, so we'll draw the linestrip in two parts for those.
dxDrawPrimitive("linestrip",true,unpack(circleCoords,firstPoint,resolution)) -- [secondPoint] is overshooting, so first let's complete the circle from [firstPoint]
dxDrawPrimitive("linestrip",true,circleCoords[resolution],unpack(circleCoords,1,secondPoint%resolution)) -- and then draw the remaining extra segments from the start of the circle to however many segments [secondPoint] went past [resolution]
elseif firstPoint < 1 then -- lua tables start at an index of 1, so 0 and anything into the negatives needs to be handled
dxDrawPrimitive("linestrip",true,unpack(circleCoords,resolution+firstPoint,resolution)) -- "how many segments before [resolution] do we have to start? Either way we complete it at [resolution]!"
dxDrawPrimitive("linestrip",true,circleCoords[resolution],unpack(circleCoords,1,secondPoint)) -- draw the remaining segments from 1 all the way to [secondPoint]
else
dxDrawPrimitive("linestrip",true,unpack(circleCoords,firstPoint,secondPoint)) -- the line isn't currently crossing the origin point of the circle at the top, so drawing this one is straight forwards
end

end
addEventHandler("onClientRender",getRootElement(),exampleRender)
</syntaxhighlight>
</section>

==See Also==
{{Drawing_functions}}

[[hu:dxDrawPrimitive]]

Template:Useful Functions

2023-01-27T17:52:30Z

Dragon: /* Player functions */ added isPlayerActuallyInVehicle

__NOTOC__
=== Table functions ===
*[[addTableChangeHandler]] » This function monitors the changes of a table.
*[[getTableFromSql]] » This functionality is used to obtain saved tables using the function ([https://wiki.multitheftauto.com/wiki/SetTableToSql SetTableToSql ]).
*[[isValueInTable]] » This function returns true if the value exists in the table, false if the value does not exist in the table.
*[[pairsByKeys]] » This function sort pairs table.
*[[rangeToTable]] » This function converts a string range to a table containing number values.
*[[setTableProtected]] » This function protects a table and makes it read-only.
*[[setTableToSql]] » This function is used to save the table in the database (sql).
*[[Sort_Functions]] » These functions are able to sort your tables by a key.
*[[table.compare]] » This function checks whether two given tables are equal.
*[[table.copy]] » This function copies a whole table and all the tables in that table.
*[[table.deepmerge]] » This function deep merges two tables. Every nested table will be correspondingly merged.
*[[table.element]] » This function returns a new table with only userdata content.
*[[table.empty]] » This function checks whether a table is empty.
*[[table.fromString]] » This function converts string to a table.
*[[table.getRandomRows]] » This function returns random rows from table.
*[[table.map]] » This function goes through a table and replaces every field with the return of the passed function, where the field's value is passed as first argument and optionally more arguments.
*[[table.merge]] » This function merges two or more tables together.
*[[table.random]] » This function retrieves a random value from a table.
*[[table.removeValue]] » This function removes a specified value from a table.
*[[table.size]] » This function returns the absolute size of a table.
*[[table.toString]] » This function converts table to a string.

=== ACL functions ===
*[[aclGroupClone]] » This function clone a group to another group with/without ACLs and/or objects.
*[[getAccountsRanks]] » This function is used to detect the account name groups and put them in the chat.
*[[getPlayerAcls]] » This function returns a table of all ACL groups on a player.
*[[getPlayersInACLGroup]] » This function returns all players in an ACL group.
*[[isPlayerInACL]] » This function checks if a player element is in an ACL group.
*[[renameAclGroup]] » This function gives an existing ACL group a new name.

=== Account functions ===
*[[getPlayerFromAccountName]] » This function is used to obtain a player by the name of his account.

=== Camera functions ===
*[[smoothMoveCamera]] » This function allows you to create a cinematic camera flight.

=== Cursor functions ===
*[[getCursorMovedOn]] » This function checks in which way the cursor is currently moving.

=== Drawing functions ===
*[[dxDrawAnimWindow]] » This function draws an animated 2D window on the screen.
*[[dxDrawBorderedRectangle]] » This is a function that will create a bordered rectangle.
*[[dxDrawBorderedText]] » This is a function that will create a bordered text.
*[[dxDrawDashedLine]] » This function draws a line with dashes.
*[[dxDrawGifImage]] » This function simulates the effect of a GIF image by using image sprites in 2D.
*[[dxDrawImage3D]] » This function draws a 3D image in GTA world.
*[[dxDrawImageOnElement]] » This function draws an image on any element.
*[[dxDrawLinedRectangle]] » This is a function that will create a rectangle outline with dx lines.
*[[dxDrawLoading]] » This function draws a loading bar on the screen.
*[[dxDrawOctagon3D]] » This function creates a 3D Octagon
*[[dxDrawPolygon]] » This function draws a custom polygon on the screen.
*[[dxDrawProgressBar]] » This function simulates a progress bar drawed using DirectDraw.
*[[dxDrawRectangle3D]] » This function draws a 3D rectangle in GTA world.
*[[dxDrawRectangleOnPlayer]] » This function draws a 3D rectangle above the player.
*[[dxDrawRing]] » This function draws a ring with dx lines.
*[[dxDrawRombo]] » This function creates a Rhombus.
*[[dxDrawSprite]] » This function draw a sprite in the 3D world.
*[[dxDrawTextOnElement]] » This function draws a text on any element.
*[[dxDrawTextOnRectangle]] » Esta funcion crea un rectangle con un texto dentro.
*[[dxDrawTriangle]] » This is a function that will create a triangle with dx lines.
*[[dxGetFontSizeFromHeight]] » This function calculates the font size from given height.
*[[dxGetRealFontHeight]] » This function calculates the height of a font.
*[[getScreenStartPositionFromBox]] » This function helps with getting the correct position for your dx-effects.
*[[wordWrap]] » This function breaks a long string into a table of separate lines limited to a specific length in pixels, for drawing separately.
*[[CreateRectangle3D]] » This is a function that will create a 3d rectangle on the player screen.
*[[DxDrawBordered3DLine]] »This function creates a bordered area with 3D dx lines.

=== Effects functions ===
*[[attachEffect]] » This function allows you attach an effect to an element.

=== Element functions ===
*[[autoAttach]] » This function attaches one element into another at the same position and rotation they are.
*[[isElementPlayer]] » This function checks whether the element is a player or not.
*[[attachElementToBone]] » This function allows you to attach an element to ped bone accurately using new bone functions.
*[[getElementsInDimension]] » This function returns a table of elements that are in the specified dimension.
*[[getElementSpeed]] » This function returns the specified element's speed in m/s, km/h or mph.
*[[getElementsWithinMarker]] » This function returns a table of elements that are within a marker's collision shape.
*[[getElementUsingData]] » This function returns table elements that contains the elements data with the given key and value.
*[[getNearestElement]] » This function returns the nearest element (of a specific type) to a player.
*[[isElementInPhotograph]] » This function checks if an element is in the player's camera picture area.
*[[isElementInRange]] » This function allows you to check if an element's range to a main point is within the maximum range.
*[[isElementMoving]]» This function checks if an element is moving.
*[[isElementWithinAColShape]]» This function checks if an element is within a collision shape element.
*[[isElementInAir]]» This function checks if an element is in air or not.
*[[multi_check]] » This function checks one element to many, handy and clean.
*[[setElementSpeed]] » This function allows you to set the speed of an element in kph or mph units.
*[[getElementDirectionCardialPoint]] » This function returns the direction of the element according to the ''wind rose''.

=== Events ===
*[[onVehicleWeaponFire]] » This code implements an event that is triggered when a player in a vehicle fires a vehicle's weapon.

=== Input functions ===
*[[bindControlKeys]] » This function allows you to bind each key bound to a control individually. Doing this bypasses a little MTA restriction.
*[[getBoundControls]] » This function returns a table of control names that are bound to the specified key.
*[[unbindControlKeys]] » This function allows you to unbind each key bound to a control individually. Use this function with [[bindControlKeys]].

=== Data functions ===
*[[byte2human]] » This function converts an integer (number of bytes) into a human-readable unit.
*[[capitalize]] » This function capitalizes a given string.
*[[convertDate]] » This function converts date to another look.
*[[convertServerTickToTimeStamp]] » This function converts server ticks to a unix timestamp.
*[[convertTextToSpeech]] » This function converts the provided text to a speech in the provided language which players can hear.
*[[findRotation3D]] » This function takes two sets of XYZ coordinates. It returns the 3D direction from point A to point B.
*[[findRotation]] » This function takes two points and returns the direction from point A to point B.
*[[formatDate]] » This function formats a date on the basis of a format string and returns it.
*[[formatNumber]] » This function formats large numbers by adding commas.
*[[generateRandomASCIIString]] » This function returns a random string which uses ASCII characters. 
*[[generateString]] » This function generates a random string with any characters.
*[[getAge]] » This function calculates the age of a given birthday.
*[[getDistanceBetweenElements]] » Returns the distance between two elements.
*[[getDistanceBetweenPointAndSegment2D]] » This function takes point coordinates and line (a segment) starting and ending coordinates. It returns the shortest distance between the point and the line.
*[[getEasterDate]] » This function returns easter date monthday and month for a given year.
*[[getFreeDimension]] » This function get free dimension.
*[[getKeyFromValueInTable]] » This function returns the key of the specified value in a table.
*[[getOffsetFromXYZ]] » This function allows you to take an entity and a position and calculate the relative offset between them accounting for rotations.
*[[getPointFromDistanceRotation]] » This function finds a point based on a starting point, direction and distance.
*[[getRealMonth]] » This function returns the current month name
*[[getRGColorFromPercentage]] »This function returns two integers representing red and green colors according to the specified percentage.
*[[getScreenRotationFromWorldPosition]] » This function returns a screen relative rotation to a world position.
*[[getTimestamp]] » This function returns the UNIX timestamp of a specified date and time.
*[[gradientString]] » This function transforms a string in a new coloured gradient string.
*[[hex2rgb]] » This function convert hex to rgb.
*[[hexColorToRGB]] » This function convert hex string/number to RGBA values.
*[[isLeapYear]] » This function returns a boolean representing if a given year is a leap year.
*[[isValidMail]] » This function checks whether a provided e-mail string is valid.
*[[removeHex]] » This function is used to remove hexadecimal numbers (colors, for example) from strings.
*[[RGBToHex]] » This function returns a string representing the color in hexadecimal.
*[[RGBToHSV]] » This function convert RGB to HSV color space.
*[[RGBToDecimal]] » This function convert RGB to Decimal color.
*[[secondsToTimeDesc]] » This function converts a plain seconds-integer into a user-friendly time description.
*[[string.count]] » This function counts the amount of occurences of a string in a string.
*[[string.explode]] » This function splits a string at a given separator pattern and returns a table with the pieces.
*[[string.insert]] » This function inserts a string within another string at a given position.
*[[switch]] » This function allows the value of a variable or expression to control the flow of program execution via a multiway branch.
*[[tocolor2rgba]] » This function convert tocolor to rgba.
*[[toHex]] » This function converts a decimal number to a hexadecimal number, as a fix to be used client-side.
*[[var dump]] » This function outputs information about one or more variables using outputConsole.
*[[wavelengthToRGBA]] » This function converts a physical wavelength of light to a RGBA color.

=== GUI functions ===
*[[centerWindow]] » This function centers a CEGUI window element responsively in any resolution.
*[[guiMoveElement]] » This function moves guiElement by/like using moveObject.
*[[guiSetStaticImageMovable]] » This function allows you to move a static image like a gui window.
*[[isMouseOnGUICloseButton]] » This function allows you to check whether the mouse cursor/pointer is within a gui-window's native close button.
*[[isMouseOnGuiElement]] » This function allows you to check whether or not your mouse is over a specific gui element, this is especially useful if the gui element has a parent. 
=====Comboboxes=====
*[[guiComboBoxAdjustHeight]] » This function adjusts a CEGUI combobox element to have the correct height.

=====Gridlists=====
*[[convertGridListToText]] » This function converts grid list contents to text.
*[[getGridListRowIndexFromText]] » This function returns the GridList row index from the specified text.
*[[guiGridListAddPlayers]] » This function add all online players to a grid list.
*[[guiGridListGetColumnIDFromTitle]] » This function gets a gridlist's column ID from the column title.
*[[guiGridListGetSelectedText]] » This function returns a string containing the inner text of a selected gridlist item.
*[[guiGridListSetColumnNonSortable]] » This function makes a gridlist column become non-sortable.
*[[isTextInGridList]] » This function checks if some text exist or not in the GridList.

=====Labels=====
*[[guiLabelAddEffect]] » This function add an effects to the gui-label like (shadow, outline).

=== Marker functions ===
*[[createMarkerAttachedTo]] » This function creates a marker that is attached to an element.

=== Math functions ===
*[[math.clamp]] » This function returns the number between range of numbers or it's minimum or maximum.
*[[math.getBezierPoint]] » Get N-th order bezier point.
*[[math.hypot]] » This function returns the Hypotenuse of the triangle given by sides x and y.
*[[math.isPointInPolygon]] » Check if point is inside polygon or not.
*[[math.lerp]] » Get val between two integer.
*[[math.percent]] » This function returns a percentage from two number values.
*[[math.polygonArea]] » Compute area of any polygon.
*[[math.randomDiff]] » Generates a pseudo-random integer that's always different from the last random number generated.
*[[math.rotVecToEulerAngle]] » Rotation Vector To Euler Angle
*[[math.round]] » Rounds a number whereas the number of decimals to keep and the method may be set.
*[[mathNumber]] » This function is a workaround for the client-side floating-point precision of 24-bits.
*[[reMap]] » Re-maps a number from one range to another.
*[[Math.percentProgress|math.percentProgress]] » Returns a percentage progress from two specific values.
*[[math.average]] » This function returns the simple arithmetic mean of multiple numbers.

=== Map functions ===
*[[assignLod]] » This function lets you conveniently generate and apply a LOD model to a mapping object.
*[[getWorldPositionFromMapPosition]] » This function converts an F11 map position to world position.

=== Ped functions ===
*[[getAlivePlayers (Client)|getAlivePlayers]] » This function returns a table of the alive players client-side.
*[[getAlivePlayersInTeam]] » This function returns a table of the alive players in a team.
*[[getGuestPlayers]] » This function gets a players not login or players Guest .
*[[getOnlineAdmins]] » This function returns a table of all logged-in administrators.
*[[getPedEyesPosition]] » This function allows you to get peds eyes position.
*[[getPedGender]] » This function allows you to get peds their gender.
*[[getPedMaxHealth]] » This function returns a pedestrians's maximum health by converting it from their maximum health stat.
*[[getPedMaxOxygenLevel]] » This function returns a ped's maximum oxygen level by converting it from their maximum underwater stamina stat.
*[[getPedWeaponSkill]] » This function returns a ped's corresponding weapon skill level name.
*[[getPedHitBone]] » This function gets the approximate number of the bone where the ped is hit.
*[[getPlayerFromNamePart]] » This function returns a player from partial name.
*[[getPlayerFromSerial]] » This function returns a player from their serial.
*[[getPlayersByData]] » This function returns a table of players that have the specified data name.
*[[getPlayersInPhotograph]] » This function returns a table of all players in photograph.
*[[getPlayersInVehicles]] » This function returns a table of the players insides vehicles from a specified dimension.
*[[isPedAiming]]» This function checks if a pedestrian is aiming their weapon.
*[[isPedAimingNearPed]] » This is similar to isPedAiming but uses a colshape to be more precise.
*[[isPedDiving]] » This feature checks that pedestrian is diving in the water.
*[[isPedDrivingVehicle]] » This function checks if a specified pedestrian is driving a vehicle.
*[[isPlayerInTeam]] » This function checks if a player is in a specified team.
*[[setPedAttack]] » This function will make a ped attack a specified target.
*[[setPedFollow]] » This function will make a ped follow a specified target.
*[[getPlayerNameFromID]] » This function will get the player name from the ID element data.

=== Player functions ===
*[[countPlayersInRange]] » This function returns the number of players that are within a certain range of the specified coordinates.
*[[getPlayerPreviousAndNextWeapon]] » This function returns the player previous and next weapon.
*[[getPlayersInRange]]» This function make a table of players within certain range.
*[[isPlayerActuallyInVehicle]]» This function checks if a player is actually in a vehicle instead of just in the process of entering.
*[[isPlayerHitByVehicle]]» This function cancels event when a element is hit by a vehicle.
*[[warpToPlayer]]» This function make player warp to another player.

=== Resource functions ===
*[[getFilesInResourceFolder]] » This function gets a list of files that are inside a folder of a resource.
*[[getResourceScripts]] » This function returns a table of the resource scripts.
*[[getResourceSettings]] » This function returns a table of the resource settings.
*[[getResourceSize]] » This function returns the size of a specified resource in kB(kilobyte)
*[[refreshResource]] » This function refreshes your resource if you changed any of the files
*[[setResourcePriority]] » This function set resource download priority group.

=== Sound functions ===
*[[isSoundFinished]] » This function checks if a sound element has finished.
*[[isSoundPlaying]] » This function checks if a sound element is playing or not.
*[[stopSoundSlowly]] » This function stop your sound element slowly.

=== Browser functions ===
*[[playVideo]] » This function plays a video on the screen.

=== Team functions ===
*[[getTeamFromColor]] » This function returns a team element by the specified color.
*[[getTeamWithFewestPlayers]] » This function returns a team element with least players of all the specified teams.

=== Vehicle functions ===
*[[findEmptyCarSeat]] » This function finds you the first empty seat in a vehicle.
*[[getNearestVehicle]] » This function gets the nearest vehicle to the specified player in a specified distance.
*[[getRandomVehicle]] » This function gets a random vehicle.
*[[getValidVehicleModels]] » This function returns a table of all valid vehicle models.
*[[getVehiclesCountByType]] » This function returns the amount of vehicles by the given type as an integer value.
*[[getVehicleTurnVelocityCenterOfMass]]» This function gets a vehicle's turn velocity relative to the vehicle's center or mass.
*[[isVehicleDoubleExhaust]] » This function checks is exhaust vehicle double.
*[[isVehicleEmpty]] » This function checks whether a vehicle is empty.
*[[isVehicleOccupied]] » This function checks if a specified vehicle is occupied.
*[[isVehicleOnRoof]] » This function checks whether vehicle is on roof.
*[[isVehicleOnFire]] » This function checks if the vehicle is on fire or not.
*[[isVehicleReversing]] » This function checks if a specified vehicle is moving backwards.
*[[isVehicleUpgraded]] » This function checks is vehicle upgraded by upgrade ID.
*[[setVehicleGravityPoint]] » This function sets a vehicle's gravity in the direction of a 3 dimensional coordinate with the strength specified.
*[[setVehicleTurnVelocityCenterOfMass]]» This function sets a vehicle's turn velocity relative to the vehicle's center or mass.
*[[setVehicleHandlingFromText]]» This function sets a vehicle's handling from text.

=== Weapon functions ===
*[[getJetpackWeaponsEnabled]] » This function returns a table of enabled weapons usable on a jetpack.

=== Object functions ===
*[[getDynamicDoorObjectOpenRatio]] » This function tells you how open a dynamic door is in a range from 0 to 1.
*[[isElementObject]] » This function tells you if an element is an object or no.

=== XML functions ===
*[[getXMLNodes]] » This function returns all children of a XML node.

=== Engine functions ===
*[[engineGetCOLsFromLibrary]] » This function gets the collision data from the col library.
*[[engineLoadIMGContainer]] » This function loads the IMG container.

=== Utility ===
*[[animate]] » This function allows you to use interpolateBetween without render event and easily used.
*[[callClientFunction]] » This function allows you to call any client-side function from the server's side.
*[[callServerFunction]] » This function allows you to call any server-side function from the client's side.
*[[check]] » This function checks if its arguments are of the right type and calls the error-function if one is not.
*[[checkPassiveTimer]] » This function allows you to use passive timers in your conditions. For example you want to prevent players repeatedly using a command.
*[[coroutine.resume]] » This function applies a fix for hidden coroutine error messages.
*[[compact]] » This function create table containing variables and their values.
*[[getBanFromName]] » This functions returns the ban of the given playername.
*[[getCurrentFPS]] » This function returns the frames per second at which GTA: SA is running.
*[[getSkinNameFromID]] » This function returns the name of the skin from the given id.
*[[IfElse]] » This function returns one of two values based on a boolean expression.
*[[isCharInString]] » This shared function allows you to check if a char specified is in a string value.
*[[isMouseInCircle]] » This function checks if a cursor position is in circular area or not.
*[[isMouseInPosition]] » This function allows you to check whether the mouse cursor/pointer is within a rectangular position.
*[[iterElements]] » This function returns ''a time-saving'' iterator for your for-loops.
*[[PlotTrajectoryAtTime]] » Calculate projectile/water trajectory.
*[[preprocessor]] » This function allow you to use gcc macros.
*[[vector3:compare]] » This method checks whether two vectors match, with optional precision.
*[[svgCreateRoundedRectangle]] » This function creates a rectangle with rounded edges.

<noinclude>[[Category:Useful Functions]]</noinclude>

IsPlayerActuallyInVehicle

2023-01-27T17:37:37Z

Dragon: Created page with "{{Useful Function}} __NOTOC__ This function provides a hacky way to recreate the client-side behavior of isPedInVehicle server-sided for player elements ONLY. It checks if a specified player is actually in a vehicle and not just in the process of entering. ==Syntax== <syntaxhighlight lang="lua">bool isPlayerActuallyInVehicle ( player thePlayer )</syntaxhighlight> ===Required Arguments=== * '''thePlayer''': a player to check if they are inside a ve..."

{{Useful Function}}
__NOTOC__
This function provides a hacky way to recreate the client-side behavior of [[isPedInVehicle]] server-sided for [[player]] elements ONLY. It checks if a specified [[player]] is actually in a [[vehicle]] and not just in the process of entering.

==Syntax==
<syntaxhighlight lang="lua">bool isPlayerActuallyInVehicle ( player thePlayer )</syntaxhighlight>

===Required Arguments===
* '''thePlayer''': a [[player]] to check if they are inside a [[vehicle]] or not.

===Returns===
Returns ''true'' if the specified [[player]] has fully completed entering a [[vehicle]] and hasn't fully completed exiting it yet, ''false'' otherwise.

==Code==
<section name="Function source" class="server" show="true">
<syntaxhighlight lang="lua">
function isPlayerActuallyInVehicle(player)
assert(isElement(player) and (getElementType(player) == "player"), "Bad argument @ isPlayerActuallyInVehicle [player expected, got " .. type(player) .. " '" .. tostring(player) .. "']")
local vehicle = getPedOccupiedVehicle(player)
if vehicle then
local x,y = getElementPosition(player)
local vx,vy = getElementPosition(vehicle)
if x == vx and y == vy then
return true
end
end
return false
end
</syntaxhighlight>
</section>

==Example==
<section name="Server" class="server" show="true">
This example will output a chat message anywhere within 50ms of a player changing their in-vehicle-state according to [[isPlayerActuallyInVehicle]].
<syntaxhighlight lang="lua">
local allPlayers = {}
function resStart()
for i,v in ipairs(getElementsByType("player")) do
allPlayers[v] = isPlayerActuallyInVehicle(v)
end
setTimer(checkInterval,50,0)
end
addEventHandler("onResourceStart",getResourceRootElement(getThisResource()),resStart)

function addPlayer()
allPlayers[source] = isPlayerActuallyInVehicle(source)
end
addEventHandler("onPlayerJoin",getRootElement(),addPlayer)

function checkInterval()
for k,v in pairs(allPlayers) do
local result = isPlayerActuallyInVehicle(k)
if not v == result then
outputChatBox(getPlayerName(k).." changed their in vehicle state to "..tostring(result))
allPlayers[k] = result
end
end
end
</syntaxhighlight></section>

Author: [[User:Dragon]]

==See also==
{{Useful_Functions}}

TakePlayerScreenShot

2023-01-24T03:33:23Z

Dragon: /* Example */ replaced current lackluster example with one that is a little more elaborate and practical

__NOTOC__
{{Server function}}
This function forces a client to capture the current screen output and send it back to the server. The image will contain the GTA HUD and the output of any dxDraw functions that are not flagged as 'post GUI'. The image specifically excludes the chat box and all GUI (including the client console). The result is received with the event [[onPlayerScreenShot]].

==Syntax==
<syntaxhighlight lang="lua">
bool takePlayerScreenShot ( player thePlayer, int width, int height [, string tag = "", int quality = 30, int maxBandwith = 5000, int maxPacketSize = 500 ] )
</syntaxhighlight>
{{OOP||[[player]]:takeScreenShot||}}
===Required Arguments===
*'''thePlayer:''' the player to get the screen capture from.
*'''width:''' the width of the capture image.
*'''height:''' the height of the capture image.

===Optional Arguments===
*'''tag:''' A string to help identify the screen capture. The string is passed to the matching [[onPlayerScreenShot]] event for your personal convenience.
*'''quality:''' Quality of the final JPEG image from 0 to 100. A lower value can reduce the memory used by the image considerably which will result in faster and less intrusive uploads.
*'''maxBandwith:''' The amount of client upload bandwidth to use (in bytes per second) when sending the image.
*'''maxPacketSize: ''' The maximum size of one packet.

===Returns===
Returns ''true'' if the function was successfully, ''false'' if invalid arguments are specified.

==Example==
===Example 1===
This example will take a player screenshot whenever a player takes a picture with the camera weapon and then send the picture to all clients, which will render the latest screenshot in the bottom right corner of their screen.

<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
local screenSizeX,screenSizeY = guiGetScreenSize() -- save the current screen dimensions
local imgtexture
local takenBy

function wepFire(weapon)
if weapon == 43 then -- if the weapon the player just fired is the camera
triggerServerEvent("onPlayerTakesPhoto",getLocalPlayer())
end
end
addEventHandler("onClientPlayerWeaponFire",getLocalPlayer(),wepFire)

function updateLatestPhoto(img)
if imgtexture then -- clean up the old dxTextrue if there is one
destroyElement(imgtexture)
end
imgtexture = dxCreateTexture(img) -- create a new dxTexture from the image data so that we can render it using dxDrawImage
takenBy = "taken by "..getPlayerName(source) -- let's also credit the photographer
end
addEvent("updatePhoto",true)
addEventHandler("updatePhoto",getRootElement(),updateLatestPhoto)

function renderPhoto()
if imgtexture then
local sizeX, sizeY = 320, 240
dxDrawImage(screenSizeX-sizeX,screenSizeY-sizeY,sizeX,sizeY,imgtexture) -- render the picture as well as the name of the photographer in the bottom right corner of the screen
dxDrawText(takenBy,screenSizeX-sizeX,screenSizeY-sizeY,screenSizeX,screenSizeY,tocolor(0,0,0))
end
end
addEventHandler("onClientRender",getRootElement(),renderPhoto)
</syntaxhighlight>
</section>
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
function requestScreenshot()
takePlayerScreenShot(source,320,240,"cameraphoto",50) -- the player just took a picture with the camera, let's request a screenshot to see what they took a photo of
end
addEvent("onPlayerTakesPhoto",true)
addEventHandler("onPlayerTakesPhoto",getRootElement(),requestScreenshot)

function incomingPlayerScreenshot(res,status,img,timestamp,tag)
if status == "ok" and tag == "cameraphoto" then -- make sure a picture was taken successfully and that we're the ones who requested this screenshot
triggerClientEvent("updatePhoto",source,img) -- trigger a client event to share the image with everyone on the server
end
end
addEventHandler("onPlayerScreenShot",getRootElement(),incomingPlayerScreenshot)
</syntaxhighlight>
</section>

==Requirements==
{{Requirements|1.3|n/a|}}

==See Also==
{{Player functions}}

DxDrawPrimitive

2023-01-23T17:15:34Z

Dragon: added another example using the linestrip type primitive

FireWeapon

2023-01-23T15:43:39Z

Dragon: added another example that does more than fire a single shot

__NOTOC__
{{Client function}}
Fires one shot from a [[Element/Weapon|custom weapon]].

==Syntax==
<syntaxhighlight lang="lua">bool fireWeapon ( weapon theWeapon )</syntaxhighlight>
{{OOP||[[Element/Weapon|weapon]]:fire}}

===Required Arguments===
* '''theWeapon:''' The weapon to be fired.

===Returns===
Returns ''true'' if the shot weapon is valid and therefore the shot was fired, ''false'' otherwise.

==Example==
<section name="Example 1" class="client" show="true">
This function creates and fires a weapon.
<syntaxhighlight lang="lua">
function createAndFire()
local weapon = createWeapon("mp5", 0, 0, 3) -- Create a MP5 at the coordinates 0, 0, 3
fireWeapon(weapon) -- Fire the weapon we spawned
end
addEventHandler("onClientResourceStart", resourceRoot, createAndFire)
</syntaxhighlight>
</section>

<section name="Example 2" class="client" show="true">
This example will create an M4, attach it to the local player and fire it every frame. Be aware that neither the weapon nor the shots are synced between players and that normally weapons don't fire every frame.

<syntaxhighlight lang="lua">
local wep
function resStart()
wep = createWeapon("m4",0,0,0) -- when the resource starts, create the M4 and attach it to the local player with an offset to place it above their head facing forwards
attachElements(wep,getLocalPlayer(),0,0,1,0,0,90)
end
addEventHandler("onClientResourceStart",getResourceRootElement(getThisResource()), resStart)

function wepFire() -- fire the M4 every frame using the "onClientRender" event
fireWeapon(wep)
end
addEventHandler("onClientRender",getRootElement(),wepFire)
</syntaxhighlight>
</section>

==Requirements==
{{Requirements|n/a|1.3.0-9.04555|}}

==See also==
{{Client weapon creation functions}}

Talk:FireWeapon

2020-05-16T02:45:34Z

Dragon: Created page with ""Returns true if the shot weapon is valid and therefore the shot was fired, false otherwise." Is this as conflicting as I think it is? If we only check if the weapon is valid,..."

"Returns true if the shot weapon is valid and therefore the shot was fired, false otherwise." Is this as conflicting as I think it is? If we only check if the weapon is valid, then a weapon without ammo would still return true despite not firing, which I think isn't really helpful for working with created weapons. If that's the case and we can't improve that, then I feel like documentation should make '''very clear''' that neither total ammo nor ammo in clip will be taken into consideration. --[[User:Dragon|Dragon]] ([[User talk:Dragon|talk]]) 02:45, 16 May 2020 (UTC)

OnPlayerWasted

2020-04-09T22:11:09Z

Dragon: Added documentation for 'killer' parameter for fall damage scenarios. Added documentation about objects being possible killers

__NOTOC__
{{Server event}}
This event is triggered when a player is killed or dies.

==Parameters==
{{New feature/item|3|1.0||<syntaxhighlight lang="lua">
int totalAmmo, element killer, int killerWeapon, int bodypart, bool stealth
</syntaxhighlight>}}

{{Deprecated_feature|3|1.0|<syntaxhighlight lang="lua">
int totalAmmo, element killer, int killerWeapon, int bodypart
</syntaxhighlight>}}

*'''totalAmmo''': an [[int]] representing the total ammo the victim had when they died.
*'''killer''': an [[element]] representing the [[player]], [[vehicle]] or [[object]] who was the killer. Deaths resulting from fall damage provide the [[vehicle]] or [[object]] landed on as the killer. If there was no killer this is ''false''.
*'''killerWeapon''': an [[int]] representing the [[Weapons|killer weapon]] or the [[Damage Types|damage type]].
*'''bodypart''': an [[int]] representing the bodypart ID the victim was hit on when they died.
{{BodyParts}}
*'''stealth''': a [[boolean]] value representing whether or not this was a stealth kill.

==Source==
The [[event system#Event source|source]] of this event is the [[player]] that died or got killed.

==Example==
This example prints the killer and bodypart to the chat when a player dies.
<syntaxhighlight lang="lua">
-- register player_Wasted as a handler for onPlayerWasted
function player_Wasted ( ammo, attacker, weapon, bodypart )
-- if there was an attacker
if ( attacker ) then
-- we declare our variable outside the following checks
local tempString
-- if the element that killed him was a player,
if ( getElementType ( attacker ) == "player" ) then
-- put the attacker, victim and weapon info in the string
tempString = getPlayerName ( attacker ).." killed "..getPlayerName ( source ).." ("..getWeaponNameFromID ( weapon )..")"
-- else, if it was a vehicle,
elseif ( getElementType ( attacker ) == "vehicle" ) then
-- we'll get the name from the attacker vehicle's driver
tempString = getPlayerName ( getVehicleController ( attacker ) ).." killed "..getPlayerName ( source ).." ("..getWeaponNameFromID ( weapon )..")"
end
-- if the victim was shot in the head, append a special message
if ( bodypart == 9 ) then
tempString = tempString.." (HEADSHOT!)"
-- else, just append the bodypart name
else
tempString = tempString.." ("..getBodyPartName ( bodypart )..")"
end
-- display the message
outputChatBox ( tempString )
-- if there was no attacker,
else
-- output a death message without attacker info
outputChatBox ( getPlayerName ( source ).." died. ("..getWeaponNameFromID ( weapon )..") ("..getBodyPartName ( bodypart )..")" )
end
end
addEventHandler ( "onPlayerWasted", getRootElement(), player_Wasted )
</syntaxhighlight>

And another example, this will spawn you in the middle of GTA SA world (x=0, y=0, z=3) after 2 seconds of your death
<syntaxhighlight lang="lua">
addEventHandler( "onPlayerWasted", getRootElement( ),
function()
setTimer( spawnPlayer, 2000, 1, source, 0, 0, 3 )
end
)
</syntaxhighlight>

{{See also/Server event|Player events}}

OnClientPlayerChangeNick

2010-07-27T15:34:54Z

Dragon: /* Example */

[[Category:Incomplete Event]]
{{Client event}}
__NOTOC__
This event is triggered when a player changes his nickname.

==Parameters==
<syntaxhighlight lang="lua">
string oldNick, string newNick
</syntaxhighlight>
*'''oldNick:''' the nickname the player had before.
*'''newNick:''' the new nickname of the player.

==Source==
The source of this event is the player that changed his nick

==Example==
This example snippet sends a lame message every time the local player changes his nick.
<syntaxhighlight lang="lua">
addEventHandler ( "onClientPlayerChangeNick", getLocalPlayer(),
function ( oldNick, newNick )
outputChatBox ( "Hi " .. oldNick .. "! Oh... You're not " .. oldNick .. " anymore, are you?", 0, 255, 0 )
outputChatBox ( "I like your new name " .. newNick .. "!", 0, 255, 0 )
end
)
</syntaxhighlight>

==See Also==
===Client player events===
{{Client_player_events}}
===Client event functions===
{{Client_event_functions}}

OnClientPlayerChangeNick

2010-07-27T15:33:49Z

Dragon: /* Example */ made the example a bit more clear

[[Category:Incomplete Event]]
{{Client event}}
__NOTOC__
This event is triggered when a player changes his nickname.

==Parameters==
<syntaxhighlight lang="lua">
string oldNick, string newNick
</syntaxhighlight>
*'''oldNick:''' the nickname the player had before.
*'''newNick:''' the new nickname of the player.

==Source==
The source of this event is the player that changed his nick

==Example==
This example snippet sends a lame message every time a player changes his nick.
<syntaxhighlight lang="lua">
addEventHandler ( "onClientPlayerChangeNick", getRootElement(),
function ( oldNick, newNick )
outputChatBox ( "Hi " .. oldNick .. "! Oh... You're not " .. oldNick .. " anymore, are you?", 0, 255, 0 )
outputChatBox ( "I like your new name " .. newNick .. "!", 0, 255, 0 )
end
)
</syntaxhighlight>

==See Also==
===Client player events===
{{Client_player_events}}
===Client event functions===
{{Client_event_functions}}

OnElementDataChange

2010-04-12T17:28:41Z

Dragon: /* Example */

__NOTOC__
{{Server event}}
This event is triggered when an elementdata entry for an element changes. A client can perform this change on the element or it can be done using [[setElementData]].

==Parameters==
<syntaxhighlight lang="lua">
string theName, var theOldValue
</syntaxhighlight>

*'''theName''': The name of the element data entry that changed
*'''theOldValue''': The old value of this entry before it changed. The new value can be accessed using [[getElementData]] ( source, theName ).

==Source==
The [[event system#Event source|source]] of this event is the [[element]] whose elementdata changed.

==Example==
<section name="Server" class="server" show="true">

This example outputs a message to players when any of their element data values is changed.

<syntaxhighlight lang="lua">
function outputChange(dataName,oldValue)
if getElementType(source) == "player" then -- check if the element is a player
local newValue = getElementData(source,dataName) -- find the new value
outputChatBox("Your element data '"..tostring(dataName).."' has changed from '"..tostring(oldValue).."' to '"..tostring(newValue).."'",source) -- output the change for the affected player
end
end
addEventHandler("onElementDataChange",getRootElement(),outputChange)
</syntaxhighlight>
</section>

[[Category:Needs Example]]

{{See also/Server event|Element events}}

OnElementDataChange

2010-04-09T14:27:01Z

Dragon: Added an example

__NOTOC__
{{Server event}}
This event is triggered when an elementdata entry for an element changes. A client can perform this change on the element or it can be done using [[setElementData]].

==Parameters==
<syntaxhighlight lang="lua">
string theName, var theOldValue
</syntaxhighlight>

*'''theName''': The name of the element data entry that changed
*'''theOldValue''': The old value of this entry before it changed. The new value can be accessed using [[getElementData]] ( source, theName ).

==Source==
The [[event system#Event source|source]] of this event is the [[element]] whose elementdata changed.

==Example==

This example outputs a message to players when any of their element data values is changed.

<syntaxhighlight lang="lua">
function outputChange(dataName,oldValue)
if getElementType(source) == "player" then -- check if the element is a player
local newValue = getElementData(source,dataName) -- find the new value
outputChatBox("Your element data '"..tostring(dataName).."' has changed from '"..tostring(oldValue).."' to '"..tostring(newValue).."'",source) -- output the change for the affected player
end
end
addEventHandler("onElementDataChange",getRootElement(),outputChange)
</syntaxhighlight>

[[Category:Needs Example]]

{{See also/Server event|Element events}}

User talk:Dragon

2009-08-20T23:04:40Z

Dragon:

<section name="Todo" class="client" show="true">
<syntaxhighlight lang="lua">
>extend magnetwheels functionality
| -different modes, detect near ground and walls
----->camera fixes ... ?
| | -remove quick changing, flickering
| | -possibility to deactivate, maybe request it
| -remove ability to use it as a way of flying
>extend xxxs functionality if playing animations backwards becomes possible
| -user controls, mime hot coffee... if i get permission to do so lols
| -maybe add female part too, multiplayer like
| -camera
>add new features to scoreboard
----->click players and get options what to do, PM, votekick, etc.
| | export a function to include new fields, for admin kick, band, spectate and such
| -clientside settings
| -request name column to become smaller or shrink, or code and submit patch for it
>spacecowboys gamemode
| -to much to do to list it here
>dark resource
| -let this become a stealth map or something with included lua to make it "dark" ;P
| -set the timer correctly so the darkness rectangle doesnt stack and activate, deactivate correctly for goggles
| -somehow add a hint that goggles are really useful on this map so more people take it on stealth start
>utsounds
| -get the original facts when which sound is played
| -clean up code... -argh
| -better quality for some sounds
| -remove headshot code and include it instead, offer setting for sniper 1 hit kill or put it in an own resource
| -a help file..??
>admin
| -possibility to dis include resource types in resource list so servers with many maps have a better survey of their resources
| -fix autologin option somehow
| -maybe help getting rid of warnings, errors and bring back its old functionality
>lag compensation
| -maybe ask talidan for a fix and an included testing session
| -search for the revision its uselessness is caused by
| -testing between dp2.3 and current
>find cause for currently emerging BAD DESYNC
>bullet holes and scratches for cars script
>chatbubbles
----->fix overlapping (for a later release)
| | -make it work
| | -make it look smooth
| | -find a good way to implement this, test CAREFULLY
| -release it
| -ask for it to become part of optional resources
>dragonsmusic
| -cycling between own stand alone resources which play the music, so you dont need to download all of them at once
| -MOAR SONGS
>external http download issue?!
>flashbang
| -sound volume depending on distance
| -when closer longer blind, when far away only for short time
| -depending where on screen it is
| -bug with rocketlauncher and sniper aim
| -dxrectangle instead, find a way to combine it with sound blending
>notifications
| -optimize the size for all resolutions
| -create a how to use guide
| -add some examples
| -release
>maps
| -check for doors to replace (because of new dynamic objects)
| -release them
| -finish hallway and add security cams
>stealth
| -add some celebration sounds in the end
>beg for community login, 3d scene and credits scene to come back
</syntaxhighlight>
</section>

2009-06-27T15:46:33Z

Dragon: changed chatbox to chatbox input line and added console and help manager, since all of them prevent cursor from being not shown by showCursor function.

__NOTOC__
{{Server client function}}
This function is used to show or hide a [[player]]'s cursor.

Note that, regardless of the cursor state you set using this function, the cursor will always be visible while the menu, the chatbox input line, the console or the help manager are open.

==Syntax==
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
bool showCursor ( player thePlayer, bool show, [ bool toggleControls = true ] )
</syntaxhighlight>

===Required Arguments===
*'''thePlayer:''' The [[player]] you want to show or hide the cursor of.
*'''show:''' A boolean value determining whether to show (''true'') or hide (''false'') the cursor.

===Optional Arguments===
{{OptionalArg}}
{{New feature|3|1.0|
*'''toggleControls:''' A boolean value determining whether to disable controls whilst the cursor is showing. ''true'' implies controls are disabled, ''false'' implies controls remain enabled.
}}

</section>
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
bool showCursor ( bool show, [ bool toggleControls = true ] )
</syntaxhighlight>

===Required Arguments===
*'''show:''' A boolean value determining whether to show (''true'') or hide (''false'') the cursor.

===Optional Arguments===
{{OptionalArg}}
{{New feature|3|1.0|
*'''toggleControls:''' A boolean value determining whether to disable controls whilst the cursor is showing. ''true'' implies controls are disabled, ''false'' implies controls remain enabled.
}}

</section>

===Returns===
Returns ''true'' if the player's cursor was shown or hidden successfully, ''false'' otherwise.

==Example==
<section name="Server" class="server" show="true">
This example shows the cursor for a player named "Dave", then outputs a message if it was shown successfully.
<syntaxhighlight lang="lua">
local thePlayer = getPlayerFromNick ( "Dave" ) -- get the player named Dave
if thePlayer then -- if we got him
showCursor ( thePlayer, true ) -- make his cursor show
if isCursorShowing ( thePlayer ) then -- did it show?
outputChatBox ( "Cursor is now showing for Dave." ) -- print a message to the chat box
end
end
</syntaxhighlight>
</section>

<section name="Client" class="client" show="true">
This example shows the cursor all the time
<syntaxhighlight lang="lua">
showCursor ( true ) -- Shows cursor
showCursor ( false ) -- Doesnt Show Cursor
</syntaxhighlight>
</section>

==See Also==
{{Cursor_functions}}