Multi Theft Auto: Wiki - User contributions [en]

SetElementData

2025-03-26T19:43:48Z

Zver-CR:

{{Server client function}}
__NOTOC__
This function stores [[element data]] under a certain key, attached to an element. Element data set using this is then synced with all clients and the server. The data can contain server-created elements, but you should avoid passing data that is not able to be synced such as xmlnodes, acls, aclgroups etc.

As element data is synced to all clients, it can generate a lot of network traffic and be heavy on performance. Events are much more efficient for sending data from a client to the server only, or from the server to a specific client. 
Usage of element data should be discouraged where your goal can be achieved with events like above, and [[table|tables]] for storing and retrieving data.
{{Tip|A simple and efficient way to make a variable known to the server and clients is to use setElementData on the [[root]] element.}}
{{Note|See [[Script security]] for tips on preventing cheaters when using events and element data.}}
{{Note|For performance reasons, never use setElementData in events that fire often (like [[onClientRender]]) without further optimization or conditions. In fact, using element data in general, can take such a toll on performance that not using it unless strictly necessary (e.g use alternatives such as storing data in tables) is recommended.}}

{{New items|3.0158|1.5.7|A subscription mode has been introduced for [[setElementData]] serverside. When setting data in subscription mode, only clients that are added through [[addElementDataSubscriber]] will receive the data, which is good for performance.
Note this mode only works when setting element data serverside. Setting data clientside still sends the update to all clients if 'synchronize' is set to true.
|20477}}

==Syntax==
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
bool setElementData ( element theElement, string key, var value [, string syncMode = "broadcast", string clientChangesPolicy = "default" ] )
</syntaxhighlight>
{{OOP||[[element]]:setData||getElementData}}

===Required Arguments===
*'''theElement:''' The [[element]] you wish to attach the data to.
*'''key:''' The key you wish to store the data under. (Maximum 128 characters.)
*'''value:''' The value you wish to store. See [[element data]] for a list of acceptable datatypes.

===Optional Arguments===
{{New items|3.0158|1.5.7|
*'''syncMode:''' Synchronization mode.
**''"broadcast"'' - Synchronize to all clients (default behavior). You can also parse ''true'' for this option.
**''"local"'' - Don't synchronize. You can also parse ''false'' for this option.
**''"subscribe"'' - Only synchronize to specific clients. See [[addElementDataSubscriber]] and [[removeElementDataSubscriber]].
|20477}}
{{New items|3.0161|1.6.0|
*'''clientChangesPolicy:''' Client changes policy.
**''"default"'' - Use '''elementdata_whitelisted''' setting from [https://wiki.multitheftauto.com/wiki/Server_mtaserver.conf#elementdata_whitelisted mtaserver.conf]
**''"allow"'' - Trust changes from clients.
**''"deny"'' - Deny client changes. The server will trigger the [[onPlayerChangesProtectedData]] event when the client attempts to change the value.
|22815}}
</section>

<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
bool setElementData ( element theElement, string key, var value [, bool synchronize = true ] )
</syntaxhighlight>
{{OOP||[[element]]:setData||getElementData}}

===Required Arguments===
*'''theElement:''' The [[element]] you wish to attach the data to.
*'''key:''' The key you wish to store the data under. (Maximum 128 characters.)
*'''value:''' The value you wish to store. See [[element data]] for a list of acceptable datatypes.

===Optional Arguments===
*'''synchronize:''' Determines whether or not the data will be synchronized with the server.
</section>

===Returns===
Returns ''true'' if the data was set successfully, ''false'' otherwise.

==Example==
Example 1
<section name="Server" class="server" show="true">
This example allows a player to add a custom tag onto their nickname, and also reverts it back to normal if they wish.
<syntaxhighlight lang="lua">
function addPlayerCustomTag ( thePlayer, command, newTag )
--Let's make sure the newTag param has been entered...
if ( newTag ) then
--Grab their current playername for saving.
local sPlayerNickname = getPlayerName ( thePlayer )
--Create their new nickname with their tag
local sNewPlayerNickname = newTag .. " " .. sPlayerNickname

--Let's first load the element data, see if it's there already
--The reason for this is that if a player were to do /addtag twice,
--the tag would be prepended a second time
local sOldNick = getElementData( thePlayer, "tempdata.originalnick" )
if ( sOldNick == false ) then
--Save their orignal nickname in their element data
setElementData ( thePlayer, "tempdata.originalnick", sPlayerNickname )
end

--Set their new nickname globally
setPlayerName ( thePlayer, sNewPlayerNickname )

--Tell them it's done
outputChatBox ( "Your new nickname has been set, to put it back to its original state you can use /deltag", thePlayer )
else
--The newTag param was not entered, give an error message
outputChatBox ( "/addtag - Incorrect syntax, Correct: /addtag <newtag>", thePlayer )
end
end
addCommandHandler ( "addtag", addPlayerCustomTag )

function removePlayerCustomTag ( thePlayer, command )
--We first need to check that they have already used /addtag, let's do that now
local sOldNick = getElementData( thePlayer, "tempdata.originalnick" )
if ( sOldNick ) then
--Great, they have a tag added, let's reset them

--First we will want to reset the element data back to its default (that being false)
setElementData ( thePlayer, "tempdata.originalnick", false )

--Now set the client name back
setPlayerName( thePlayer, sOldNick )

--Notify them
outputChatBox ( "Your old nickname has been set", thePlayer )
end
end
addCommandHandler ( "deltag", removePlayerCustomTag )
</syntaxhighlight>
</section>

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.6.0-9.22815|Added clientChangesPolicy argument}}

==See Also==
{{Element_functions}}

[[pt-br:SetElementData]]
[[tr:setElementData]]

SetElementData

2025-03-26T18:56:19Z

Zver-CR:

{{Server client function}}
__NOTOC__
This function stores [[element data]] under a certain key, attached to an element. Element data set using this is then synced with all clients and the server. The data can contain server-created elements, but you should avoid passing data that is not able to be synced such as xmlnodes, acls, aclgroups etc.

As element data is synced to all clients, it can generate a lot of network traffic and be heavy on performance. Events are much more efficient for sending data from a client to the server only, or from the server to a specific client. 
Usage of element data should be discouraged where your goal can be achieved with events like above, and [[table|tables]] for storing and retrieving data.
{{Tip|A simple and efficient way to make a variable known to the server and clients is to use setElementData on the [[root]] element.}}
{{Note|See [[Script security]] for tips on preventing cheaters when using events and element data.}}
{{Note|For performance reasons, never use setElementData in events that fire often (like [[onClientRender]]) without further optimization or conditions. In fact, using element data in general, can take such a toll on performance that not using it unless strictly necessary (e.g use alternatives such as storing data in tables) is recommended.}}

{{New items|3.0158|1.5.7|A subscription mode has been introduced for [[setElementData]] serverside. When setting data in subscription mode, only clients that are added through [[addElementDataSubscriber]] will receive the data, which is good for performance.
Note this mode only works when setting element data serverside. Setting data clientside still sends the update to all clients if 'synchronize' is set to true.
|20477}}

==Syntax==
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
bool setElementData ( element theElement, string key, var value [, string syncMode = "broadcast", string clientChangesPolicy = "default" ] )
</syntaxhighlight>
{{OOP||[[element]]:setData||getElementData}}

===Required Arguments===
*'''theElement:''' The [[element]] you wish to attach the data to.
*'''key:''' The key you wish to store the data under. (Maximum 128 characters.)
*'''value:''' The value you wish to store. See [[element data]] for a list of acceptable datatypes.

===Optional Arguments===
{{New items|3.0158|1.5.7|
*'''syncMode:''' Synchronization mode.
**''"broadcast"'' - Synchronize to all clients (default behavior). You can also parse ''true'' for this option.
**''"local"'' - Don't synchronize. You can also parse ''false'' for this option.
**''"subscribe"'' - Only synchronize to specific clients. See [[addElementDataSubscriber]] and [[removeElementDataSubscriber]].
|20477}}
{{New items|3.0161|1.6.0|
*'''clientChangesPolicy:''' Client changes policy.
**''"default"'' - Use '''elementdata_whitelisted''' setting from [https://wiki.multitheftauto.com/wiki/Server_mtaserver.conf#elementdata_whitelisted mtaserver.conf]
**''"allow"'' - Trust changes from clients.
**''"deny"'' - Deny client changes. The server will trigger the [[onPlayerChangesProtectedData]] event when the client attempts to change the value.
|22815}}
</section>

<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
bool setElementData ( element theElement, string key, var value [, bool synchronize = true ] )
</syntaxhighlight>
{{OOP||[[element]]:setData||getElementData}}

===Required Arguments===
*'''theElement:''' The [[element]] you wish to attach the data to.
*'''key:''' The key you wish to store the data under. (Maximum 128 characters.)
*'''value:''' The value you wish to store. See [[element data]] for a list of acceptable datatypes.

===Optional Arguments===
*'''synchronize:''' Determines whether or not the data will be synchronized with the server.
</section>

===Returns===
Returns ''true'' if the data was set successfully, ''false'' otherwise.

==Example==
Example 1
<section name="Server" class="server" show="true">
This example allows a player to add a custom tag onto their nickname, and also reverts it back to normal if they wish.
<syntaxhighlight lang="lua">
function addPlayerCustomTag ( thePlayer, command, newTag )
--Let's make sure the newTag param has been entered...
if ( newTag ) then
--Grab their current playername for saving.
local sPlayerNickname = getPlayerName ( thePlayer )
--Create their new nickname with their tag
local sNewPlayerNickname = newTag .. " " .. sPlayerNickname

--Let's first load the element data, see if it's there already
--The reason for this is that if a player were to do /addtag twice,
--the tag would be prepended a second time
local sOldNick = getElementData( thePlayer, "tempdata.originalnick" )
if ( sOldNick == false ) then
--Save their orignal nickname in their element data
setElementData ( thePlayer, "tempdata.originalnick", sPlayerNickname )
end

--Set their new nickname globally
setPlayerName ( thePlayer, sNewPlayerNickname )

--Tell them it's done
outputChatBox ( "Your new nickname has been set, to put it back to its original state you can use /deltag", thePlayer )
else
--The newTag param was not entered, give an error message
outputChatBox ( "/addtag - Incorrect syntax, Correct: /addtag <newtag>", thePlayer )
end
end
addCommandHandler ( "addtag", addPlayerCustomTag )

function removePlayerCustomTag ( thePlayer, command )
--We first need to check that they have already used /addtag, let's do that now
local sOldNick = getElementData( thePlayer, "tempdata.originalnick" )
if ( sOldNick ) then
--Great, they have a tag added, let's reset them

--First we will want to reset the element data back to its default (that being false)
setElementData ( thePlayer, "tempdata.originalnick", false )

--Now set the client name back
setPlayerName( thePlayer, sOldNick )

--Notify them
outputChatBox ( "Your old nickname has been set", thePlayer )
end
end
addCommandHandler ( "deltag", removePlayerCustomTag )
</syntaxhighlight>
</section>
[[tr:setElementData]]

==See Also==
[[pt-br:SetElementData]]
{{Element_functions}}

Template:Useful Functions

2023-09-27T20:20:24Z

Zver-CR:

__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.
*[[isPlayerACLAdmin]] » This function checks if a player element belong to Admin group in ACL

=== 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.

=== Colshape functions ===
*[[createGarageColShape]] » This function creates a collision shape from the specified garage.

=== Cursor functions ===
*[[getCursorMovedOn]] » This function checks in which way the cursor is currently moving.
*[[setCursorCenteredOnRectangle]] » This functions will center the cursor inside a rectangle.

=== 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.
*[[setScreenFlash]] » This function will make the screen flash(like a screenshot).

=== 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]].
*[[isCommandHandlerAdded]] » This function allows you to check if a command is added or not in the respective resource.

=== 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.
*[[getElementRelatedAngle]] » This function returns the related angle between one element to another. This is useful to check which side an element is to another.
*[[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.

=== 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.
*[[setVehicleWheelModel]] » This function changes the wheel model of the informed vehicle.

=== 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>

GetFilesInResourceFolder

2023-09-27T19:29:33Z

Zver-CR:

{{Useful Function}}<lowercasetitle></lowercasetitle>__NOTOC__
This function lists all files in a resource folder. '''PS''': This function should only be performed on server-side.
{{Note|The listing is only done with files that are specified in the '''meta.xml''' file in attributes named '''src'''.}}

==Syntax==
<syntaxhighlight lang="lua">table, table getFilesInResourceFolder ( string directory, [ resource theResource ] )</syntaxhighlight>

===Required Arguments===
* '''directory''': The [[string]] that will determine the folder in which to list files. To get all files, use <code>'/'</code>

===Optional Arguments===
{{OptionalArg}}
* '''theResource''': The [[resource]] to be searched. If not specified, the search is performed on the resource where the function was executed.

===Returns===
Returns two [[table|tables]], the 1st storing the name / path of the obtained files, and the 2nd storing only the name of the files (with their respective extensions). Otherwise it returns '''false'''.
======Format======
* 1st table: <code style='color: green'> {'Folder1/Folder2/file.ext', 'Folder1/file2.ext', 'file3.ext'} </code>
* 2nd table: <code style='color: green'> {'file.ext', 'file2.ext', 'file3.ext'} </code>

==Source code==
<section name="Server-side" class="server" show="false">
<syntaxhighlight lang="lua">
function getFilesInResourceFolder(path, res)
if (triggerServerEvent) then error('The @getFilesInResourceFolder function should only be used on server-side', 2) end

if not (type(path) == 'string') then
error("@getFilesInResourceFolder argument #1. Expected a 'string', got '"..type(path).."'", 2)
end

if not (tostring(path):find('/$')) then
error("@getFilesInResourceFolder argument #1. The path must contain '/' at the end to make sure it is a directory.", 2)
end

res = (res == nil) and getThisResource() or res
if not (type(res) == 'userdata' and getUserdataType(res) == 'resource-data') then
error("@getFilesInResourceFolder argument #2. Expected a 'resource-data', got '"..(type(res) == 'userdata' and getUserdataType(res) or tostring(res)).."' (type: "..type(res)..")", 2)
end

local files = {}
local files_onlyname = {}
local thisResource = res == getThisResource() and res or false
local charsTypes = '%.%_%w%d%|%\%<%>%:%(%)%&%;%#%?%*'
local resourceName = getResourceName(res)
local Meta = xmlLoadFile(':'..resourceName ..'/meta.xml')
if not Meta then error("(@getFilesInResourceFolder) Could not get the 'meta.xml' for the resource '"..resourceName.."'", 2) end
for _, nod in ipairs(xmlNodeGetChildren(Meta)) do
local srcAttribute = xmlNodeGetAttribute(nod, 'src')
if (srcAttribute) then
local onlyFileName = tostring(srcAttribute:match('/(['..charsTypes..']+%.['..charsTypes..']+)') or srcAttribute)
local theFile = fileOpen(thisResource and srcAttribute or ':'..resourceName..'/'..srcAttribute)
if theFile then
if (path == '/') then
table.insert(files, srcAttribute)
table.insert(files_onlyname, onlyFileName)
else
local filePath = fileGetPath(theFile)
filePath = filePath:gsub('/['..charsTypes..']+%.['..charsTypes..']+', '/'):gsub(':'..resourceName..'/', '')
if (filePath == tostring(path)) then
table.insert(files, srcAttribute)
table.insert(files_onlyname, onlyFileName)
end
end
fileClose(theFile)
else
outputDebugString("(@getFilesInResourceFolder) Could not check file '"..onlyFileName.."' from resource '"..nomeResource.."'", 2)
end
end
end
xmlUnloadFile(Meta)
return #files > 0 and files or false, #files_onlyname > 0 and files_onlyname or false
end
</syntaxhighlight>
</section>

==Example==
<section name="Example 1 (Server)" class="server" show="true">
This example create the command handler '''/filesfrom <folder> [resource_name]''' which displays in the chat some information about the data obtained from the file search.
<syntaxhighlight lang="lua">
function searchFiles(player, cmd, folderName, resName)
if (hasObjectPermissionTo(player, 'function.banPlayer', false)) then -- The player will only proceed with this command if he is allowed to ban
if (folderName) then -- If you specified the folder name, then
local theRes
if (resName) then -- If you specified the name of the resource then we will define it
theRes = getResourceFromName(tostring(resName))
if not theRes then -- If there is no resource with the specified name, then we will let you know
return outputChatBox("#FF0000##FFFFFF There is no resource named '"..resName.."'", player, 255, 255, 255, true)
end
end
local files, onlyFilesName = getFilesInResourceFolder(folderName, theRes) -- then we will do the search
if (files and onlyFilesName) then -- If everything went well, then we show the response data
outputChatBox('===== Got files! =====', player, 255, 255, 255, true)
outputChatBox('=> Folder: '..tostring(folderName), player, 255, 255, 255, true)
outputChatBox('=> Resource: '..tostring(resName), player, 255, 255, 255, true)
outputChatBox('=> Total files: '..tostring(#files)..' arquivos', player, 255, 255, 255, true)
outputChatBox('=> Files: #00FF00'..tostring(table.concat(onlyFilesName, ', ')), player, 255, 255, 255, true)
outputChatBox('==============================', player, 255, 255, 255, true)
else
outputChatBox("#FF0000##FFFFFF Couldn't get file list", player, 255, 255, 255, true)
end
else
outputChatBox('#FF0000##FFFFFF Specify the name of the folder you want to search for files', player, 255, 255, 255, true)
end
else
outputChatBox('# You are not allowed to run this command.', player, 255, 0, 0, false)
end
end
addCommandHandler('filesfrom', searchFiles)
</syntaxhighlight>
</section>
<section name="Example 2 (Server)" class="server" show="true">
This example create the command handler '''/fileshere <folder>''' which displays in the chat information about the files obtained by the useful function.
<syntaxhighlight lang="lua">
function searchFiles(player, cmd, folderName)
if (hasObjectPermissionTo(player, 'function.banPlayer', false)) then -- Only those who are allowed to ban players will continue with this command.
if (folderName) then -- If you specified the name of the folder you want to search, then ...
local files, onlyFilesName = getFilesInResourceFolder(folderName)
if (files and onlyFilesName) then -- If we obtained data about the files, then we will display
outputChatBox('===== Got files! =====', player, 255, 255, 255, true)
outputChatBox('=> Folder: '..tostring(folderName), player, 255, 255, 255, true)
outputChatBox('=> Resource: '..getResourceName(getThisResource()), player, 255, 255, 255, true)
outputChatBox('=> Total files: '..tostring(#files)..' arquivos', player, 255, 255, 255, true)
outputChatBox('=> Files: #00FF00'..tostring(table.concat(onlyFilesName, ', ')), player, 255, 255, 255, true)
outputChatBox('==============================', player, 255, 255, 255, true)
else
outputChatBox('#FF0000##FFFFFF Could not retrieve files in the specified folder', player, 255, 255, 255, true)
end
else
outputChatBox('#FF0000##FFFFFF Specify the name of the folder you want to search', player, 255, 255, 255, true)
end
else
outputChatBox('# You are not allowed to run this command', player, 255, 0, 0, false)
end
end
addCommandHandler('fileshere', searchFiles)
</syntaxhighlight>
</section>

==Credits==
*'''Author:''' [[User:Lettify|KronoS Lettify]].

==See Also==
{{Useful_Functions}}
[[PT-BR:GetFilesInResourceFolder]]

GetFilesInResourceFolder

2023-09-27T19:09:13Z

Zver-CR: Undo revision 77671 by Zver-CR (talk)

{{Useful Function}}<lowercasetitle></lowercasetitle>__NOTOC__
This function lists all files in a resource folder. '''PS''': This function should only be performed on server-side.
{{Note|The listing is only done with files that are specified in the '''meta.xml''' file in attributes named '''src'''.}}

==Syntax==
<syntaxhighlight lang="lua">table, table getFilesInResourceFolder ( string directory, [ resource theResource ] )</syntaxhighlight>

===Required Argument===
* '''directory''': The [[string]] that will determine the folder in which to list files. To get all files, use <code>'/'</code>

===Optional Argument===
{{BR/ArgOpcional}}
* '''theResource''': The [[resource]](userdata) to be searched. If not specified, the search is performed on the resource where the function was executed.

===Return===
Return two [[table|tables]], the 1st storing the name / path of the obtained files, and the 2nd storing only the name of the files (with their respective extensions). Otherwise it returns '''false'''.
======Format======
* 1st table: <code style='color: green'> {'Folder1/Folder2/file.ext', 'Folder1/file2.ext', 'file3.ext'} </code>
* 2nd table: <code style='color: green'> {'file.ext', 'file2.ext', 'file3.ext'} </code>

==Source code==
<section name="Server-side" class="server" show="false">
<syntaxhighlight lang="lua">
function getFilesInResourceFolder(path, res)
if (triggerServerEvent) then error('The @getFilesInResourceFolder function should only be used on server-side', 2) end

if not (type(path) == 'string') then
error("@getFilesInResourceFolder argument #1. Expected a 'string', got '"..type(path).."'", 2)
end

if not (tostring(path):find('/$')) then
error("@getFilesInResourceFolder argument #1. The path must contain '/' at the end to make sure it is a directory.", 2)
end

res = (res == nil) and getThisResource() or res
if not (type(res) == 'userdata' and getUserdataType(res) == 'resource-data') then
error("@getFilesInResourceFolder argument #2. Expected a 'resource-data', got '"..(type(res) == 'userdata' and getUserdataType(res) or tostring(res)).."' (type: "..type(res)..")", 2)
end

local files = {}
local files_onlyname = {}
local thisResource = res == getThisResource() and res or false
local charsTypes = '%.%_%w%d%|%\%<%>%:%(%)%&%;%#%?%*'
local resourceName = getResourceName(res)
local Meta = xmlLoadFile(':'..resourceName ..'/meta.xml')
if not Meta then error("(@getFilesInResourceFolder) Could not get the 'meta.xml' for the resource '"..resourceName.."'", 2) end
for _, nod in ipairs(xmlNodeGetChildren(Meta)) do
local srcAttribute = xmlNodeGetAttribute(nod, 'src')
if (srcAttribute) then
local onlyFileName = tostring(srcAttribute:match('/(['..charsTypes..']+%.['..charsTypes..']+)') or srcAttribute)
local theFile = fileOpen(thisResource and srcAttribute or ':'..resourceName..'/'..srcAttribute)
if theFile then
if (path == '/') then
table.insert(files, srcAttribute)
table.insert(files_onlyname, onlyFileName)
else
local filePath = fileGetPath(theFile)
filePath = filePath:gsub('/['..charsTypes..']+%.['..charsTypes..']+', '/'):gsub(':'..resourceName..'/', '')
if (filePath == tostring(path)) then
table.insert(files, srcAttribute)
table.insert(files_onlyname, onlyFileName)
end
end
fileClose(theFile)
else
outputDebugString("(@getFilesInResourceFolder) Could not check file '"..onlyFileName.."' from resource '"..nomeResource.."'", 2)
end
end
end
xmlUnloadFile(Meta)
return #files > 0 and files or false, #files_onlyname > 0 and files_onlyname or false
end
</syntaxhighlight>
</section>
 
==Examples==
====Example 1====
<section name="Server-side" class="server" show="true">
This example create the command handler '''/filesfrom <folder> [resource_name]''' which displays in the chat some information about the data obtained from the file search.
<syntaxhighlight lang="lua">
function searchFiles(player, cmd, folderName, resName)
if (hasObjectPermissionTo(player, 'function.banPlayer', false)) then -- The player will only proceed with this command if he is allowed to ban
if (folderName) then -- If you specified the folder name, then
local theRes
if (resName) then -- If you specified the name of the resource then we will define it
theRes = getResourceFromName(tostring(resName))
if not theRes then -- If there is no resource with the specified name, then we will let you know
return outputChatBox("#FF0000##FFFFFF There is no resource named '"..resName.."'", player, 255, 255, 255, true)
end
end
local files, onlyFilesName = getFilesInResourceFolder(folderName, theRes) -- then we will do the search
if (files and onlyFilesName) then -- If everything went well, then we show the response data
outputChatBox('===== Got files! =====', player, 255, 255, 255, true)
outputChatBox('=> Folder: '..tostring(folderName), player, 255, 255, 255, true)
outputChatBox('=> Resource: '..tostring(resName), player, 255, 255, 255, true)
outputChatBox('=> Total files: '..tostring(#files)..' arquivos', player, 255, 255, 255, true)
outputChatBox('=> Files: #00FF00'..tostring(table.concat(onlyFilesName, ', ')), player, 255, 255, 255, true)
outputChatBox('==============================', player, 255, 255, 255, true)
else
outputChatBox("#FF0000##FFFFFF Couldn't get file list", player, 255, 255, 255, true)
end
else
outputChatBox('#FF0000##FFFFFF Specify the name of the folder you want to search for files', player, 255, 255, 255, true)
end
else
outputChatBox('# You are not allowed to run this command.', player, 255, 0, 0, false)
end
end
addCommandHandler('filesfrom', searchFiles)
</syntaxhighlight>
</section>

====Exemplo 2====
<section name="Lado servidor" class="server" show="true">
This example create the command handler '''/fileshere <folder>''' which displays in the chat information about the files obtained by the useful function.
<syntaxhighlight lang="lua">
function searchFiles(player, cmd, folderName)
if (hasObjectPermissionTo(player, 'function.banPlayer', false)) then -- Only those who are allowed to ban players will continue with this command.
if (folderName) then -- If you specified the name of the folder you want to search, then ...
local files, onlyFilesName = getFilesInResourceFolder(folderName)
if (files and onlyFilesName) then -- If we obtained data about the files, then we will display
outputChatBox('===== Got files! =====', player, 255, 255, 255, true)
outputChatBox('=> Folder: '..tostring(folderName), player, 255, 255, 255, true)
outputChatBox('=> Resource: '..getResourceName(getThisResource()), player, 255, 255, 255, true)
outputChatBox('=> Total files: '..tostring(#files)..' arquivos', player, 255, 255, 255, true)
outputChatBox('=> Files: #00FF00'..tostring(table.concat(onlyFilesName, ', ')), player, 255, 255, 255, true)
outputChatBox('==============================', player, 255, 255, 255, true)
else
outputChatBox('#FF0000##FFFFFF Could not retrieve files in the specified folder', player, 255, 255, 255, true)
end
else
outputChatBox('#FF0000##FFFFFF Specify the name of the folder you want to search', player, 255, 255, 255, true)
end
else
outputChatBox('# You are not allowed to run this command', player, 255, 0, 0, false)
end
end
addCommandHandler('fileshere', searchFiles)
</syntaxhighlight>
</section>

==Credits==
*'''Author:''' [[User:Lettify|KronoS Lettify]].
 
==See Also==
{{Useful_Functions}}
[[PT-BR:GetFilesInResourceFolder]]

GetFilesInResourceFolder

2023-09-27T19:08:05Z

Zver-CR:

{{Useful Function}}<lowercasetitle></lowercasetitle>__NOTOC__
This function lists all files in a resource folder. '''PS''': This function should only be performed on server-side.
{{Note|The listing is only done with files that are specified in the '''meta.xml''' file in attributes named '''src'''.}}

==Syntax==
<syntaxhighlight lang="lua">table, table getFilesInResourceFolder ( string directory, [ resource theResource ] )</syntaxhighlight>

===Required Argument===
* '''directory''': The [[string]] that will determine the folder in which to list files. To get all files, use <code>'/'</code>

===Optional Argument===
{{BR/ArgOpcional}}
* '''theResource''': The [[resource]](userdata) to be searched. If not specified, the search is performed on the resource where the function was executed.

===Return===
Return two [[table|tables]], the 1st storing the name / path of the obtained files, and the 2nd storing only the name of the files (with their respective extensions). Otherwise it returns '''false'''.
======Format======
* 1st table: <code style='color: green'> {'Folder1/Folder2/file.ext', 'Folder1/file2.ext', 'file3.ext'} </code>
* 2nd table: <code style='color: green'> {'file.ext', 'file2.ext', 'file3.ext'} </code>

==Source code==
<section name="Server-side" class="server" show="false">
<syntaxhighlight lang="lua">
function getFilesInResourceFolder(path, res)
if (triggerServerEvent) then error('The @getFilesInResourceFolder function should only be used on server-side', 2) end

if not (type(path) == 'string') then
error("@getFilesInResourceFolder argument #1. Expected a 'string', got '"..type(path).."'", 2)
end

if not (tostring(path):find('/$')) then
error("@getFilesInResourceFolder argument #1. The path must contain '/' at the end to make sure it is a directory.", 2)
end

res = (res == nil) and getThisResource() or res
if not (type(res) == 'userdata' and getUserdataType(res) == 'resource-data') then
error("@getFilesInResourceFolder argument #2. Expected a 'resource-data', got '"..(type(res) == 'userdata' and getUserdataType(res) or tostring(res)).."' (type: "..type(res)..")", 2)
end

local files = {}
local files_onlyname = {}
local thisResource = res == getThisResource() and res or false
local charsTypes = '%.%_%w%d%|%\%<%>%:%(%)%&%;%#%?%*'
local resourceName = getResourceName(res)
local Meta = xmlLoadFile(':'..resourceName ..'/meta.xml')
if not Meta then error("(@getFilesInResourceFolder) Could not get the 'meta.xml' for the resource '"..resourceName.."'", 2) end
for _, nod in ipairs(xmlNodeGetChildren(Meta)) do
local srcAttribute = xmlNodeGetAttribute(nod, 'src')
if (srcAttribute) then
local onlyFileName = tostring(srcAttribute:match('/(['..charsTypes..']+%.['..charsTypes..']+)') or srcAttribute)
local theFile = fileOpen(thisResource and srcAttribute or ':'..resourceName..'/'..srcAttribute)
if theFile then
if (path == '/') then
table.insert(files, srcAttribute)
table.insert(files_onlyname, onlyFileName)
else
local filePath = fileGetPath(theFile)
filePath = filePath:gsub('/['..charsTypes..']+%.['..charsTypes..']+', '/'):gsub(':'..resourceName..'/', '')
if (filePath == tostring(path)) then
table.insert(files, srcAttribute)
table.insert(files_onlyname, onlyFileName)
end
end
fileClose(theFile)
else
outputDebugString("(@getFilesInResourceFolder) Could not check file '"..onlyFileName.."' from resource '"..nomeResource.."'", 2)
end
end
end
xmlUnloadFile(Meta)
return #files > 0 and files or false, #files_onlyname > 0 and files_onlyname or false
end
</syntaxhighlight>
</section>
 
==Examples==
====Example 1====
<section name="Server-side" class="server" show="true">
This example create the command handler '''/filesfrom <folder> [resource_name]''' which displays in the chat some information about the data obtained from the file search.
<syntaxhighlight lang="lua">
function searchFiles(player, cmd, folderName, resName)
if (hasObjectPermissionTo(player, 'function.banPlayer', false)) then -- The player will only proceed with this command if he is allowed to ban
if (folderName) then -- If you specified the folder name, then
local theRes
if (resName) then -- If you specified the name of the resource then we will define it
theRes = getResourceFromName(tostring(resName))
if not theRes then -- If there is no resource with the specified name, then we will let you know
return outputChatBox("#FF0000##FFFFFF There is no resource named '"..resName.."'", player, 255, 255, 255, true)
end
end
local files, onlyFilesName = getFilesInResourceFolder(folderName, theRes) -- then we will do the search
if (files and onlyFilesName) then -- If everything went well, then we show the response data
outputChatBox('===== Got files! =====', player, 255, 255, 255, true)
outputChatBox('=> Folder: '..tostring(folderName), player, 255, 255, 255, true)
outputChatBox('=> Resource: '..tostring(resName), player, 255, 255, 255, true)
outputChatBox('=> Total files: '..tostring(#files)..' arquivos', player, 255, 255, 255, true)
outputChatBox('=> Files: #00FF00'..tostring(table.concat(onlyFilesName, ', ')), player, 255, 255, 255, true)
outputChatBox('==============================', player, 255, 255, 255, true)
else
outputChatBox("#FF0000##FFFFFF Couldn't get file list", player, 255, 255, 255, true)
end
else
outputChatBox('#FF0000##FFFFFF Specify the name of the folder you want to search for files', player, 255, 255, 255, true)
end
else
outputChatBox('# You are not allowed to run this command.', player, 255, 0, 0, false)
end
end
addCommandHandler('filesfrom', searchFiles)
</syntaxhighlight>
</section>

====Exemplo 2====
<section name="Lado servidor" class="server" show="true">
This example create the command handler '''/fileshere <folder>''' which displays in the chat information about the files obtained by the useful function.
<syntaxhighlight lang="lua">
function searchFiles(player, cmd, folderName)
if (hasObjectPermissionTo(player, 'function.banPlayer', false)) then -- Only those who are allowed to ban players will continue with this command.
if (folderName) then -- If you specified the name of the folder you want to search, then ...
local files, onlyFilesName = getFilesInResourceFolder(folderName)
if (files and onlyFilesName) then -- If we obtained data about the files, then we will display
outputChatBox('===== Got files! =====', player, 255, 255, 255, true)
outputChatBox('=> Folder: '..tostring(folderName), player, 255, 255, 255, true)
outputChatBox('=> Resource: '..getResourceName(getThisResource()), player, 255, 255, 255, true)
outputChatBox('=> Total files: '..tostring(#files)..' arquivos', player, 255, 255, 255, true)
outputChatBox('=> Files: #00FF00'..tostring(table.concat(onlyFilesName, ', ')), player, 255, 255, 255, true)
outputChatBox('==============================', player, 255, 255, 255, true)
else
outputChatBox('#FF0000##FFFFFF Could not retrieve files in the specified folder', player, 255, 255, 255, true)
end
else
outputChatBox('#FF0000##FFFFFF Specify the name of the folder you want to search', player, 255, 255, 255, true)
end
else
outputChatBox('# You are not allowed to run this command', player, 255, 0, 0, false)
end
end
addCommandHandler('fileshere', searchFiles)
</syntaxhighlight>
</section>

==Credits==
*'''Author:''' [[User:Lettify|KronoS Lettify]].
 
==See Also==

==See Also==
{{Useful_Functions}}
[[PT-BR:GetFilesInResourceFolder]]

IsElementObject

2023-09-27T19:07:58Z

Zver-CR:

{{Useful_Function}}
This function tells you if an element is an object or no.

==Syntax==
<syntaxhighlight lang="lua">float isElementObject ( element theElement )</syntaxhighlight>

===Required Arguments===
*'''theElement:''' The element that you wish to check if is an object or no.

===Returns===
Returns an object.

==Code==
<syntaxhighlight lang="lua">
function isElementObject(element)
if isElement(element) and getElementType(element) == "object" then
return element
end
end
</syntaxhighlight>

'''Author: Hydra45'''

==See Also==
{{Useful_Functions}}

GetDynamicDoorObjectOpenRatio

2023-09-27T19:07:52Z

Zver-CR:

{{Useful_Function}}
This function tells you how open a dynamic (interactive - pushable) door is (the 'open ratio') just like the [[GetVehicleDoorOpenRatio]] function.

{{Note|This function only works properly on objects that have the special collision-response IDE flag #6 (SWINGDOOR). These are: '''1491''', '''1492''', '''1494''', '''1499''', '''1502''', '''1523'''}}

==Syntax==
<syntaxhighlight lang="lua">float getDynamicDoorObjectOpenRatio ( object theObject )</syntaxhighlight>

===Required Arguments===
*'''theObject:''' The [[object]] that you wish to get the door open ratio of.

===Returns===
Returns a number between 0 and 1 that indicates how open the door is. 0 is closed, and 1 is fully open. Returns false if invalid arguments are passed.

==Code==
<syntaxhighlight lang="lua">
function getDynamicDoorObjectOpenRatio(theObject)
if isElement(theObject) then
if getElementType(theObject) == "object" then
local angularVelocity = select(3, getElementAngularVelocity(theObject))

if math.abs(angularVelocity) > 0 then
local objectMatrix = getElementMatrix(theObject)
local initialAngle = select(3, getElementRotation(theObject, "ZXY"))
local currentAngle = -math.deg(math.atan2(objectMatrix[2][1], objectMatrix[2][2]))

if initialAngle + 180 >= currentAngle then
if initialAngle - 180 > currentAngle then
currentAngle = currentAngle + 360
end
else
currentAngle = currentAngle - 360
end

return math.abs(currentAngle - initialAngle) / 108
end

return 0
end
end

return false
end
</syntaxhighlight>

==See Also==
{{Useful_Functions}}

SetVehicleHandlingFromText

2023-09-27T19:07:46Z

Zver-CR:

{{Useful Function}}
==Syntax==
<syntaxhighlight lang="lua">vehicle setVehicleHandlingFromText( element vehicle, string handling)</syntaxhighlight>
===Required Arguments===
* '''vehicle''': The vehicle that needs to be installed handling.
* '''handling''': Text of handling.

==Code==
<section name="Server side Script" class="server" show="true">
<syntaxhighlight lang="lua">
local countHandlingTable = {
[1] = "mass",
[2] = "turnMass",
[3] = "dragCoeff",
[4] = "centerOfMassX",
[5] = "centerOfMassY",
[6] = "centerOfMassZ",
[7] = "percentSubmerged",
[8] = "tractionMultiplier",
[9] = "tractionLoss",
[10] = "tractionBias",
[11] = "numberOfGears",
[12] = "maxVelocity",
[13] = "engineAcceleration",
[14] = "engineInertia",
[15] = "driveType",
[16] = "engineType",
[17] = "brakeDeceleration",
[18] = "brakeBias",
[19] = "ABS",
[20] = "steeringLock",
[21] = "suspensionForceLevel",
[22] = "suspensionDamping",
[23] = "suspensionHighSpeedDamping",
[24] = "suspensionUpperLimit",
[25] = "suspensionLowerLimit",
[26] = "suspensionFrontRearBias",
[27] = "suspensionAntiDiveMultiplier",
[28] = "seatOffsetDistance",
[29] = "collisionDamageMultiplier",
[30] = "monetary",
[31] = "modelFlags",
[32] = "handlingFlags",
[33] = "headLight",
[34] = "tailLight",
[35] = "animGroup",
}

local driveTypes = {
["4"] = "awd",
["r"] = "rwd",
["f"] = "fwd",
}

function setVehicleHandlingFromText (vehicle, text)
local t = {}
local carID = vehicle.model
local tText = split(text, " ")
table.remove (tText, 1)
local countHandling = 1
for i, v in ipairs (tText) do
t[countHandlingTable[i]] = v
end

local acceptCenterMass = false
local centerMass = {x = nil, y = nil, z = nil}
for i, v in pairs (t) do
if i == "centerOfMassX" then
centerMass.x = tonumber(v)
elseif i == "centerOfMassY" then
centerMass.y = tonumber(v)
elseif i == "centerOfMassZ" then
centerMass.z = tonumber(v)
else
if centerMass.x and centerMass.y and centerMass.z and not acceptCenterMass then
setVehicleHandling (vehicle, "centerOfMass", {centerMass.x, centerMass.y, centerMass.z})
acceptCenterMass = true
end

if i == "modelFlags" or i == "handlingFlags" then
setVehicleHandling (vehicle, i, "0x"..tostring(v))
elseif i == "driveType" then
setVehicleHandling (vehicle, i, driveTypes[v])
else
setVehicleHandling (vehicle, i, tonumber(v) or tostring(v))
end
end
end
end
</syntaxhighlight></section>

==See Also==
{{Useful_Functions}}

GetNearestVehicle

2023-09-27T19:07:40Z

Zver-CR:

{{Note|You can use [[GetNearestElement|getNearestElement]] for other element types, and not just vehicles}}
{{Useful Function}}
==Syntax==
<syntaxhighlight lang="lua">vehicle getNearestVehicle( element thePlayer )</syntaxhighlight>
===Required Arguments===
* '''thePlayer''': The player you want to get the nearest vehicle of.

===Returns===
Return a vehicle element if success, false if there's no vehicles in a 10meter circle..
==Code==
<section name="Server- and/or clientside Script" class="both" show="true">
<syntaxhighlight lang="lua">
function getNearestVehicle(player,distance)
local lastMinDis = distance-0.0001
local nearestVeh = false
local px,py,pz = getElementPosition(player)
local pint = getElementInterior(player)
local pdim = getElementDimension(player)

for _,v in pairs(getElementsByType("vehicle")) do
local vint,vdim = getElementInterior(v),getElementDimension(v)
if vint == pint and vdim == pdim then
local vx,vy,vz = getElementPosition(v)
local dis = getDistanceBetweenPoints3D(px,py,pz,vx,vy,vz)
if dis < distance then
if dis < lastMinDis then
lastMinDis = dis
nearestVeh = v
end
end
end
end
return nearestVeh
end

</syntaxhighlight></section>

==See Also==
{{Useful_Functions}}

Sort Functions

2023-09-27T19:07:34Z

Zver-CR:

{{Useful_Function}}

==Code==
'''Sorting Algorithms provided by DreTaX

<syntaxhighlight lang="lua">
table insertSortingByIndex(table t, int SortByKey)
table fixedBubbleSortingByIndex(table t, int SortByKey)
</syntaxhighlight>

<section name="Function source" class="both" show="true">

Insert Sorting works possibly the fastest way If we don't know how sorted our array is.
You need to specify a table, and the table's index which we will be using to sort with.
For Example if our table has values like this, then you would specify 3:
{player, vehicle, playerid, npc}
local table = insertSortingByIndex(table, 3)
<syntaxhighlight lang="lua">
function insertSortingByIndex(array, e)
local data = array
for i = 2, #data do
local j = i - 1
local ass = data[i]
while j > 0 and data[j][e] > ass[e] do
data[j + 1] = data[j]
j = j - 1
end
data[j + 1] = ass
end
return data
end
</syntaxhighlight>

o(n^2) Sorting algorithm for lua.
<syntaxhighlight lang="lua">
function fixedBubbleSortingByIndex(array, e)
local data = array
local i = #data
while i >= 2 do
local idx = 0
for j = 1, (i - 1) do
if data[j][e] > data[j + 1][e] then
local holder = data[j][e]
data[j][e] = data[j + 1][e]
data[j + 1][e] = holder
idx = j
end
end
i = idx
end
return data
end
</syntaxhighlight>

==Usage==
<syntaxhighlight lang="lua">
local TestArray = {
{1, "test"},
{33, "test"},
{-32, "test"},
{-1, "test"},
{5, "test"},
{11, "test"},
{968, "test"},
{723, "test"},
{33, "test"},
{16, "test"},
{4, "test"},
{5, "test"},
}
local SortedTestArray = fixedBubbleSortingByIndex(TestArray, 1)
for k, v in pairs(SortedTestArray) do
outputChatBox("Value: " .. v[1])
end
local SortedTestArray2 = insertSortingByIndex(TestArray, 1)
for k, v in pairs(SortedTestArray2) do
outputChatBox("Value: " .. v[1])
end
</syntaxhighlight>

</section>

==See Also==
{{Useful_Functions}}

ReMap

2023-09-27T19:07:29Z

Zver-CR:

{{Useful_Function}}
Re-maps a number from one range to another.

==Syntax==
<syntaxhighlight lang="lua">int/float reMap(float value, float low1, float high1, float low2, float high2)</syntaxhighlight>

===Required Arguments===
* '''value''': The incoming value to be converted
* '''low1''': Lower bound of the value's current range
* '''high1''': Upper bound of the value's current range
* '''low2''': Lower bound of the value's target range
* '''high2''': Upper bound of the value's target range

===Returns===
Returns the re-mapped number.

==Code==
<syntaxhighlight lang="lua">
function reMap(value, low1, high1, low2, high2)
return low2 + (value - low1) * (high2 - low2) / (high1 - low1)
end
</syntaxhighlight>

==Example==
<section name="Clientside Example" class="client" show="true">
<syntaxhighlight lang="lua" lang="lua">
local alpha = 127.5
local opacity = reMap(alpha, 0, 255, 0, 1)

-- And the "opacity" return 0.5 because 255/2 = 127.5 and 0 to 1 range is 0.5

-- Reverse:
local opacity = 0.5
local alpha = reMap(opacity, 0, 1, 0, 255)

-- And the "alpha " return 127.5 because 1/2 = 0.5 and 0 to 255 range is 127.5
</syntaxhighlight>
</section>

==See Also==
{{Useful_Functions}}

AssignLod

2023-09-27T19:07:22Z

Zver-CR:

{{Useful_Function}}
__NOTOC__

This function is used to conveniently create a LOD for map objects.

{{Note|In most cases you will still need to use [[engineSetModelLODDistance]] besides this function to avoid drawing distance of map objects becoming 1 meter or the script appearing not to load them at all. Refer to the second example on that page, it's a client-side function and cannot be used next to assignLOD.}}

===Required Arguments===
* '''element''': The element (model) you would like to generate a LOD for

==Code==
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
function assignLOD(element)
local lod = createObject(getElementModel(element),0, 0 ,0, 0, 0, 0, true)
setElementDimension(lod,getElementDimension(element))
setElementPosition(lod, getElementPosition(element))
setElementRotation(lod, getElementRotation(element))
setElementCollisionsEnabled(lod,false)
setLowLODElement(element,lod)
return lod
end
</syntaxhighlight>
</section>

==Example==
<section name="Server" class="server" show="true">
This example shows how to correctly call the function by embedding it into the target element's createObject (for map models).
Maps must first be converted from .map to .lua (createObject) before the LOD creation script will work per the example.

<syntaxhighlight lang="lua">
addEventHandler ("onResourceStart", resourceRoot,
function()
assignLOD(createObject(2283, -820.107421875, 512.89978027344, 21.44261932373, 0, 0, 22.4990234375))
assignLOD(createObject(1238, -823.825421875, 524.15778027344, 16.12261932373))
assignLOD(createObject(1238, -829.204421875, 536.33978027344, 15.98161932373))
end
)

function assignLOD(element)
local lod = createObject(getElementModel(element),0, 0 ,0, 0, 0, 0, true)
setElementDimension(lod,getElementDimension(element))
setElementPosition(lod, getElementPosition(element))
setElementRotation(lod, getElementRotation(element))
setElementCollisionsEnabled(lod,false)
setLowLODElement(element,lod)
return lod
end
</syntaxhighlight></section>

==See Also==
{{Useful_Functions}}

RU/Полный античит MTA для форк-проектов

2023-06-25T14:48:59Z

Zver-CR:

__NOTOC__ {{Примечание|Информация на этой странице не относится к официальным сборкам MTA.}}

Форки MTA, которым недостаточно использовать "обычный netc для форков" (из bdata/netc.dll), как описано на вики-странице [[Forks]], из-за того, что он предлагает очень ограниченную античит-защиту, могут изучить возможности использования нового netc варианта: "полного античита для форков". Это, однако, имеет свои ограничения, относящиеся к особенностям вашего форк-проекта и реализации, которые нелегко объяснить, но эта страница стремится сделать это как можно точнее.

''Эта операция превратит ваш форк в проект с "надлежащим античитом, основанным на методе исправлений", как описано в спойлере в этой теме: https://forum.multitheftauto.com/topic/66858-bounty-for-finding-security-flaws-and-working-cheats-in-mta/, а не максимум 15% 'основанным на сигнатурах' античитом, как описано на вики-странице [[Forks]] для обычных форков.''

Основная идея:
* Модуль netc "с полным античитом для форков" будет предоставлять 95% функций античита, имеющихся в официальных MTA (multitheftauto.com > Кнопка "Download") сборках.
* Чем больше несовместимых функций/реализаций (пользовательских изменений) имеет ваш форк-проект, которые '''вы''' можете отключить (добавив их в белый список обнаружения: '''disableac''' массив в '''mtaserver.conf''', как описано на странице [https://wiki.multitheftauto.com/wiki/RU/Anti-cheat_guide#%3Cdisableac%3E%3C/disableac%3E Anti-cheat guide / Руководство по античиту: DISABLEAC]), тем ниже будет указанное число защиты в процентах.
** '''Например''', если вам нужно отключить 3 различных типа обнаружения (допустим, для российских форков, учитывая загрузку внешних модов вне MTA API/limit adjuster'а, наиболее распространёнными являются: 5, 6, 21), вы получите 85% оставшейся античит-защиты. Хотя это число относительно, так как это даёт разработчикам читов возможность использовать именно эти отключенные категории обнаружения для обеспечения работы их читов/хаков, и эти 3 кода уже предоставляют некоторые конкретные пути для записи в память GTA. 

Понимаете, к чему всё это идёт? Ниже в этой статье появится ссылка на "полный античит для форков", и то, что вы будете делать с ним - это метод проб и ошибок. Попытка интегрировать полную поддержку античита в ваш форк - это вопрос "Мы можем попробовать, и если это сработает, то будет здорово.. если нам придётся отключить некоторые обнаружения, то процент защиты будет выше, чем у обычного античита форков: 15% и это уже огромный выигрыш.." и во многом зависит от меры возможностей. Потому что причина, по которой мы разделили netc форков (из bdata/netc.dll) на тот, в котором отсутствует большинство античит-функций, может быть понятна любому опытному разработчику: netc модуль (античит) не рассчитан на все типы настроек, которые разработчик форка может добавить в свою кодовую базу, это было сделано в духе предоставления максимальной свободы и гибкости. Тем более, что многие форки имеют не самых лучших разработчиков, не понимающих, почему им лучше следовать рекомендациям MTA (mtasa-blue) по написанию кода, структуре проекта и максимально приближать свои пользовательские реализации так, как это обычно делает участник MTA, прошедший проверку (ревью) кода. Таким образом, здесь происходит отделение 'чистых' изменений от 'грязного моддинга', который также часто встречается в российских форках, '''использующих один или несколько следующих подходов к кодовой базе своего проекта:
''' 

* Реализация моддинговых GTA: SA проектов внешним 'грязным' способом, как limit adjuster (fastman92 и т.д.)
* Необработанная (raw) загрузка модифицированных данных GTA: SA & .IMG файлов, через распространение предварительно модифицированных установочных папок GTA среди игроков форк клиента. Тем самым полностью игнорируя MTA API для замены моделей и различных игровых процессов.
* Различные грязные патчи, в широком смысле описанные в абзаце выше. Также включает в себя несоблюдение рекомендаций MTA по "Raw memory access" (необработанному доступу к памяти), найденных здесь: https://github.com/multitheftauto/mtasa-blue/wiki/Dev-Tips, что является значительным фактором риска для сценариев, не ожидаемых netc.dll (античитом), так как если он защищает от модификаций памяти, зная их происхождение, и вы просто поместите грязный 'writeProcessMemory' или memcpy в случайный .cpp файл, это вызовет нарушение. Это далеко не всё, и это плохой пример, но просто чтобы вы поняли, почему существуют несовместимости.

=== Получение максимального % античит-защиты ===

Поняв вышесказанное, а также то, что мы стараемся изо всех сил, так как такое использование в качестве "полного античита" для форков никогда не входило в наши планы, и что было бы трудно поддерживать пользовательские модификации каждого, вы можете понять, что мы не можем помочь вам выяснить, что является несовместимым сразу после того, как вы начнёте тестировать netc "с полным античитом" в своём форке. Поэтому вы сами должны либо отключить столько обнаружений, сколько требуется (если вы не можете их исправить - где 'не можете' является показателем отсутствия инженерного опыта), либо, что ещё лучше, разработать исправления, которые позволят вам избежать отключения слишком многих или любых типов обнаружения, тем самым максимизируя потенциальный % античит-функций.

Это означает, что без поддержки команды MTA вам предстоит выяснить, какие настройки/интеграции/несоблюдения MTA API/примеры проблем, описанные ранее в этой статье.. являются виновниками каждого конкретного типа обнаружения, который отправляет вам кики античита после добавления netc "с полным античитом" в ваш форк для тестирования. Мы советуем вам очистить свои интеграции, чтобы избежать необходимости много копаться вручную/выяснять виновника. Для этого обратите внимание на пункты маркированного списка из предыдущего абзаца. Однако, если же прямой виновник найден, приложив все свои усилия, вы должны без каких-либо указаний со стороны MTA придумать альтернативные (более чистые, более соответствующие рекомендациям MTA по написанию кода, API и структуре проекта.. следовательно, менее вероятно несовместимые с полным античитом и тем, что он ожидает) реализации проблемной настройки, найденной в кодовой базе вашего форка. Вы можете видеть, где возможность использовать 'полный античит для форков' становится скорее благосклонностью, чем данностью, особенно с тем состоянием кодовой базы, в котором многие форки, не начав свою разработку по сценарию 'полного античита', выросли, просто написав то, что работает для них, не учитывая такие аспекты. Общая картина того, почему мы не будем поддерживать процесс реинжиниринга, теперь должна быть ясна. Если вы не можете с этим справиться, либо наймите кого-то с большим опытом в компьютерных науках и инженерии, либо отключите больше типов обнаружения античита, и довольствуйтесь всем, что выше 15% обычного netc для форков, лучше что-то, чем ничего. '''Но мы не сможем протянуть руку помощи.''' Любое непонимание этих концепций указывает на отсутствие полноты разработчика (индивидуальных навыков, возможностей для роста) и не может быть отражено на разработчиках MTA.

= '''Давайте перейдём к делу''' =

Если вы считаете, что поняли все концепции, описанные в этой статье, вы можете приступить к внедрению "полного античита для форков":

'''СКАЧАЙТЕ: https://mirror-cdn.multitheftauto.com/bdata/fork-support/netc.dll''' (для использования ''вместо'' "bdata/netc.dll" из стандартного mtasa-blue buildactions/install_data.lua)
Обратите внимание, что версия netc.dll по указанной выше ссылке будет регулярно обновляться, чтобы предоставить форкам все античит-улучшения, поставляемые также и для официальной MTA. Поэтому рекомендуется регулярно получать обновления для вашего форка для обеспечения оптимальной безопасности & надёжности античита

{{Примечание|
* Важно: Начиная с июня 2023 года, вы должны извлечь все коммиты (получить все изменения) mtasa-blue (обновить до 1.6) и синхронизировать кодовую базу вашего форка, чтобы использовать последнюю версию netc, представленную по ссылке выше. Существуют несовместимые изменения, которые требуют обновления с обеих сторон. Предлагаемый netc модуль подходит для форка, основанного на MTA 1.6
}}
{{Примечание|
* Важно: Вы сами несёте ответственность за добавление средства проверки целостности/подлинности файлов, так как очевидно, что поскольку игровые DLL собираются вами (а не нами), нет возможности внедрить такие уникальные DLL в наши внутренние контрольные списки netc, равно как и нет ничего в других модулях для проверки самого netc. Если вы не доработаете это, читер может просто заменить любой модуль или добавить читерскую полезную нагрузку (payload) с помощью редактирования PE, это самый большой фактор риска при использовании "полного античита для форков". Как далеко вы хотели бы зайти с проверкой файлов, например, решить усилить её в пользовательском режиме (usermode) (с heartbeat'ами или около того) или использовать собственный дополнительный античит-драйвер в режиме ядра (kernelmode), зависит от вас и уровня приверженности безопасности вашего проекта. Если всё, что вас волнует, это небольшая преграда в отношении читерства, вы можете использовать базовую проверку файлов (MD5/SHA256) для всех игровых модулей

Есть ещё много подобных узких мест, которые слишком сложны для простого объяснения, но основаны на принципе "ничто никогда не бывает на 100% безопасным", и многие из них относятся к мосту между официальной MTA и форками, использующими 'полный античит'. Также полезно поразмыслить над всем этим в целом: Команда MTA потратила годы на создание античит-технологии и предоставляет многое форкам, если они того пожелают, бесплатно. Рассматривайте это как основной слой античита, который уже защищает многое в GTA, мы помогаем вам не создавать такое огромное количество технологий самостоятельно. Теперь о том, что ещё вы делаете, например, видите это как основной слой, а затем также создаёте свой собственный дополнительный слой античита, возможно, даже на уровне новичка, технически понятном вашим разработчикам, не имеющим серьёзного опыта разработки античитов - это полностью зависит от вашей креативности и того, насколько серьёзно вы относитесь к своему проекту. Если вы хотите дополнить основной слой, предоставляемый нами, то можете это сделать.
}}

- Замените netc.dll в вашем форк-проекте на вышеуказанный "поддерживаемый для форков" netc с полным античитом.
- Убедитесь, что тип сборки в version.h изменён на UNSTABLE, согласно рекомендациям "массового потребления" для форков в комментариях: [https://github.com/multitheftauto/mtasa-blue/blob/master/Shared/sdk/version.h Shared/sdk/version.h]. В противном случае, вы сведёте на нет все усилия по получению полной античит-защиты.

- Убедитесь, что вы обновили кодовую базу вашего форка до активной основной версии (для которой netc.dll), '''мастер'''-коммита mtasa-blue, по крайней мере до версии "Default", указанной на [https://nightly.mtasa.com/ver/] как "Auto-update default" для последней основной версии, затем сопоставьте указанную ревизию с SHA1-хешем коммита с помощью этого инструмента: https://buildinfo.mtasa.com/index.php - это означает, что не следует использовать начальный выпуск (версию, которая имеет метку выпуска на github), потому что MTA использует модель "MTA как услуга", где игроки получают регулярные обновления, содержащие все основные изменения для оптимального качества и опыта использования новых функций. Последние выпуски netc.dll основаны на этом и могут требовать присутствия мастер-изменений.

- Для ваших выделенных серверов/узлов, к которым будут подключаться игроки, используйте эти net модули: 
Linux x64: https://mirror-cdn.multitheftauto.com/bdata/net_64.so (переименуйте в "net.so") 
Windows x64: https://mirror-cdn.multitheftauto.com/bdata/net_64.dll (переименуйте в "net.dll") 
Никогда не используйте x86 сервер для вашего форка, это плохо по многим причинам. Такое не поощряется и не приведёт к хорошим результатам.

Давайте продолжим с настройкой клиента и 'полного античита'. 

- Столкнитесь с некоторыми киками античита в вашем форк-клиенте, этап проб и ошибок начинается здесь. Теперь используйте предыдущие части этого руководства, чтобы либо отключить типы обнаружения античита с помощью disableac в mtaserver.conf, либо, что ещё лучше, потратьте больше сил разработчиков на правильное исправление & очистку ваших пользовательских реализаций, как советовали ранее, чтобы сохранить как можно больше % античит-защиты. Мы советуем не опускаться ниже 85% (как в примере с 'disableac' кодами: 5, 6, 21 было упомянуто, что это относительно 85% и то, что требуется большинству российских тяжёлых модифицированных форков для немедленного запуска и возможности вам подключиться).

Заключительные слова: всегда будет лучше не быть форком в первую очередь. Используйте официальный клиент MTA и просто создайте сервер, со временем со своим пользовательским лаунчером, который будет подключать непосредственно к вашему ряду серверов. Просто внесите все настройки, которые вам нужны (причина для создания форка), взяв за основу "upstream" и создайте PR, Pull request (пул-реквест), используя официальный репозиторий MTA https://github.com/multitheftauto/mtasa-blue, чтобы все выиграли, а вы соблюдали лицензию & не сталкивались с препятствиями, включая античит и приток новых игроков, которые возникают при создании форка. MTA обычно имеет 30000 игроков онлайн одновременно, что также является огромным притоком новых игроков для открытия своего сообщества. Лучше просто не быть форком, но если вам действительно нужно, эта страница является нашим активным взаимодействием с форками для получения лучшего уровня античит-защиты. 
Мы создали этот вариант netc.dll "с полным античитом для форков" в ноябре/декабре 2022 года и опробовали практические результаты и некоторые специфические исправления для лучшей поддержки, с 2 крупнейшими российскими MTA форками, оба из которых готовятся выпустить обновление, включающее это в ближайшие несколько месяцев. Мы также взаимодействовали с разработчиками небольших форков, которые, однако, решили злоупотребить этим (а вместе с этим и нашим доверием), немедленно став токсичными и пытаясь продать netc модуль "с полным античитом", который мы им дали, что побудило написать и в спешке опубликовать эту вики-статью. Нехорошо, и, пожалуйста, не ведитесь на предложения от упомянутого круга токсичных разработчиков форков, пытающихся продать вам такой netc "с полным античитом", когда вы можете получить более новую версию из официального источника, от нас в этой статье. Работа над этой статьёй в контексте упомянутого инцидента обсуждалась в MTA development discord (приглашение: https://discord.gg/GNN6PRtTnu) в этом посте: https://discord.com/channels/801330706252038164/801330706252038170/1044757943071023155 и аналогично в основном, официальном MTA discord (приглашение: https://discord.gg/mtasa) в этом посте: https://discord.com/channels/278474088903606273/278521065435824128/1044758439357849661

[[EN:Forks_Full_AC]]

RU/Полный античит MTA для форк-проектов

2023-06-22T18:14:16Z

Zver-CR:

__NOTOC__ {{Примечание|Информация на этой странице не относится к официальным сборкам MTA.}}

Форки MTA, которым недостаточно использовать "обычный netc для форков" (из bdata/netc.dll), как описано на вики-странице [[Forks]], из-за того, что он предлагает очень ограниченную античит-защиту, могут изучить возможности использования нового netc варианта: "полного античита для форков". Это, однако, имеет свои ограничения, относящиеся к особенностям вашего форк-проекта и реализации, которые нелегко объяснить, но эта страница стремится сделать это как можно точнее.

''Эта операция превратит ваш форк в проект с "надлежащим античитом, основанным на методе исправлений", как описано в спойлере в этой теме: https://forum.multitheftauto.com/topic/66858-bounty-for-finding-security-flaws-and-working-cheats-in-mta/, а не максимум 15% 'основанным на сигнатурах' античитом, как описано на вики-странице [[Forks]] для обычных форков.''

Основная идея:
* Модуль netc "с полным античитом для форков" будет предоставлять 95% функций античита, имеющихся в официальных MTA (multitheftauto.com > Кнопка "Download") сборках.
* Чем больше несовместимых функций/реализаций (пользовательских изменений) имеет ваш форк-проект, которые '''вы''' можете отключить (добавив их в белый список обнаружения: '''disableac''' массив в '''mtaserver.conf''', как описано на странице [https://wiki.multitheftauto.com/wiki/RU/Anti-cheat_guide#%3Cdisableac%3E%3C/disableac%3E Anti-cheat guide / Руководство по античиту: DISABLEAC]), тем ниже будет указанное число защиты в процентах.
** '''Например''', если вам нужно отключить 3 различных типа обнаружения (допустим, для российских форков, учитывая загрузку внешних модов вне MTA API/limit adjuster'а, наиболее распространёнными являются: 5, 6, 21), вы получите 85% оставшейся античит-защиты. Хотя это число относительно, так как это даёт разработчикам читов возможность использовать именно эти отключенные категории обнаружения для обеспечения работы их читов/хаков, и эти 3 кода уже предоставляют некоторые конкретные пути для записи в память GTA. 

Понимаете, к чему всё это идёт? Ниже в этой статье появится ссылка на "полный античит для форков", и то, что вы будете делать с ним - это метод проб и ошибок. Попытка интегрировать полную поддержку античита в ваш форк - это вопрос "Мы можем попробовать, и если это сработает, то будет здорово.. если нам придётся отключить некоторые обнаружения, то процент защиты будет выше, чем у обычного античита форков: 15% и это уже огромный выигрыш.." и во многом зависит от меры возможностей. Потому что причина, по которой мы разделили netc форков (из bdata/netc.dll) на тот, в котором отсутствует большинство античит-функций, может быть понятна любому опытному разработчику: netc модуль (античит) не рассчитан на все типы настроек, которые разработчик форка может добавить в свою кодовую базу, это было сделано в духе предоставления максимальной свободы и гибкости. Тем более, что многие форки имеют не самых лучших разработчиков, не понимающих, почему им лучше следовать рекомендациям MTA (mtasa-blue) по написанию кода, структуре проекта и максимально приближать свои пользовательские реализации так, как это обычно делает участник MTA, прошедший проверку (ревью) кода. Таким образом, здесь происходит отделение 'чистых' изменений от 'грязного моддинга', который также часто встречается в российских форках, '''использующих один или несколько следующих подходов к кодовой базе своего проекта:
''' 

* Реализация моддинговых GTA: SA проектов внешним 'грязным' способом, как limit adjuster (fastman92 и т.д.)
* Необработанная (raw) загрузка модифицированных данных GTA: SA & .IMG файлов, через распространение предварительно модифицированных установочных папок GTA среди игроков форк клиента. Тем самым полностью игнорируя MTA API для замены моделей и различных игровых процессов.
* Различные грязные патчи, в широком смысле описанные в абзаце выше. Также включает в себя несоблюдение рекомендаций MTA по "Raw memory access" (необработанному доступу к памяти), найденных здесь: https://github.com/multitheftauto/mtasa-blue/wiki/Dev-Tips, что является значительным фактором риска для сценариев, не ожидаемых netc.dll (античитом), так как если он защищает от модификаций памяти, зная их происхождение, и вы просто поместите грязный 'writeProcessMemory' или memcpy в случайный .cpp файл, это вызовет нарушение. Это далеко не всё, и это плохой пример, но просто чтобы вы поняли, почему существуют несовместимости.

=== Получение максимального % античит-защиты ===

Поняв вышесказанное, а также то, что мы стараемся изо всех сил, так как такое использование в качестве "полного античита" для форков никогда не входило в наши планы, и что было бы трудно поддерживать пользовательские модификации каждого, вы можете понять, что мы не можем помочь вам выяснить, что является несовместимым сразу после того, как вы начнёте тестировать netc "с полным античитом" в своём форке. Поэтому вы сами должны либо отключить столько обнаружений, сколько требуется (если вы не можете их исправить - где 'не можете' является показателем отсутствия инженерного опыта), либо, что ещё лучше, разработать исправления, которые позволят вам избежать отключения слишком многих или любых типов обнаружения, тем самым максимизируя потенциальный % античит-функций.

Это означает, что без поддержки команды MTA вам предстоит выяснить, какие настройки/интеграции/несоблюдения MTA API/примеры проблем, описанные ранее в этой статье.. являются виновниками каждого конкретного типа обнаружения, который отправляет вам кики античита после добавления netc "с полным античитом" в ваш форк для тестирования. Мы советуем вам очистить свои интеграции, чтобы избежать необходимости много копаться вручную/выяснять виновника. Для этого обратите внимание на пункты маркированного списка из предыдущего абзаца. Однако, если же прямой виновник найден, приложив все свои усилия, вы должны без каких-либо указаний со стороны MTA придумать альтернативные (более чистые, более соответствующие рекомендациям MTA по написанию кода, API и структуре проекта.. следовательно, менее вероятно несовместимые с полным античитом и тем, что он ожидает) реализации проблемной настройки, найденной в кодовой базе вашего форка. Вы можете видеть, где возможность использовать 'полный античит для форков' становится скорее благосклонностью, чем данностью, особенно с тем состоянием кодовой базы, в котором многие форки, не начав свою разработку по сценарию 'полного античита', выросли, просто написав то, что работает для них, не учитывая такие аспекты. Общая картина того, почему мы не будем поддерживать процесс реинжиниринга, теперь должна быть ясна. Если вы не можете с этим справиться, либо наймите кого-то с большим опытом в компьютерных науках и инженерии, либо отключите больше типов обнаружения античита, и довольствуйтесь всем, что выше 15% обычного netc для форков, лучше что-то, чем ничего. '''Но мы не сможем протянуть руку помощи.''' Любое непонимание этих концепций указывает на отсутствие полноты разработчика (индивидуальных навыков, возможностей для роста) и не может быть отражено на разработчиках MTA.

= '''Давайте перейдём к делу''' =

Если вы считаете, что поняли все концепции, описанные в этой статье, вы можете приступить к внедрению "полного античита для форков":

'''СКАЧАЙТЕ: https://mirror-cdn.multitheftauto.com/bdata/fork-support/netc.dll''' (для использования ''вместо'' "bdata/netc.dll" из стандартного mtasa-blue buildactions/install_data.lua)
Обратите внимание, что версия netc.dll по указанной выше ссылке будет регулярно обновляться, чтобы предоставить форкам все античит-улучшения, поставляемые также и для официальной MTA. Поэтому рекомендуется регулярно получать обновления для вашего форка для обеспечения оптимальной безопасности & надёжности античита

{{Примечание|
* Важно: Начиная с июня 2023 года, вы должны извлечь все коммиты (получить все изменения) mtasa-blue (обновить до 1.6) и синхронизировать кодовую базу вашего форка, чтобы использовать последнюю версию netc, представленную по ссылке выше. Существуют несовместимые изменения, которые требуют обновления с обеих сторон. Предлагаемый netc модуль подходит для форка, основанного на MTA 1.6
}}
{{Примечание|
* Важно: Вы сами несёте ответственность за добавление средства проверки целостности/подлинности файлов, так как очевидно, что поскольку игровые DLL собираются вами (а не нами), нет возможности внедрить такие уникальные DLL в наши внутренние контрольные списки netc, равно как и нет ничего в других модулях для проверки самого netc. Если вы не доработаете это, читер может просто заменить любой модуль или добавить читерскую полезную нагрузку (payload) с помощью редактирования PE, это самый большой фактор риска при использовании "полного античита для форков". Как далеко вы хотели бы зайти с проверкой файлов, например, решить усилить её в пользовательском режиме (usermode) (с heartbeat'ами или около того) или использовать режим ядра (kernelmode), зависит от вас и уровня приверженности безопасности вашего проекта. Если всё, что вас волнует, это небольшая преграда в отношении читерства, вы можете использовать базовую проверку файлов (MD5/SHA256) для всех игровых модулей
}}

- Замените netc.dll в вашем форк-проекте на вышеуказанный "поддерживаемый для форков" netc с полным античитом.
- Убедитесь, что тип сборки в version.h изменён на UNSTABLE, согласно рекомендациям "массового потребления" для форков в комментариях: [https://github.com/multitheftauto/mtasa-blue/blob/master/Shared/sdk/version.h Shared/sdk/version.h]. В противном случае, вы сведёте на нет все усилия по получению полной античит-защиты.

- Убедитесь, что вы обновили кодовую базу вашего форка до активной основной версии (для которой netc.dll), '''мастер'''-коммита mtasa-blue, по крайней мере до версии "Default", указанной на [https://nightly.mtasa.com/ver/] как "Auto-update default" для последней основной версии, затем сопоставьте указанную ревизию с SHA1-хешем коммита с помощью этого инструмента: https://buildinfo.mtasa.com/index.php - это означает, что не следует использовать начальный выпуск (версию, которая имеет метку выпуска на github), потому что MTA использует модель "MTA как услуга", где игроки получают регулярные обновления, содержащие все основные изменения для оптимального качества и опыта использования новых функций. Последние выпуски netc.dll основаны на этом и могут требовать присутствия мастер-изменений.

- Столкнитесь с некоторыми киками античита в вашем форк-клиенте, этап проб и ошибок начинается здесь. Теперь используйте предыдущие части этого руководства, чтобы либо отключить типы обнаружения античита с помощью disableac в mtaserver.conf, либо, что ещё лучше, потратьте больше сил разработчиков на правильное исправление & очистку ваших пользовательских реализаций, как советовали ранее, чтобы сохранить как можно больше % античит-защиты. Мы советуем не опускаться ниже 85% (как в примере с 'disableac' кодами: 5, 6, 21 было упомянуто, что это относительно 85% и то, что требуется большинству российских тяжёлых модифицированных форков для немедленного запуска и возможности вам подключиться).

Заключительные слова: всегда будет лучше не быть форком в первую очередь. Используйте официальный клиент MTA и просто создайте сервер, со временем со своим пользовательским лаунчером, который будет подключать непосредственно к вашему ряду серверов. Просто внесите все настройки, которые вам нужны (причина для создания форка), взяв за основу "upstream" и создайте PR, Pull request (пул-реквест), используя официальный репозиторий MTA https://github.com/multitheftauto/mtasa-blue, чтобы все выиграли, а вы соблюдали лицензию & не сталкивались с препятствиями, включая античит и приток новых игроков, которые возникают при создании форка. MTA обычно имеет 30000 игроков онлайн одновременно, что также является огромным притоком новых игроков для открытия своего сообщества. Лучше просто не быть форком, но если вам действительно нужно, эта страница является нашим активным взаимодействием с форками для получения лучшего уровня античит-защиты. 
Мы создали этот вариант netc.dll "с полным античитом для форков" в ноябре/декабре 2022 года и опробовали практические результаты и некоторые специфические исправления для лучшей поддержки, с 2 крупнейшими российскими MTA форками, оба из которых готовятся выпустить обновление, включающее это в ближайшие несколько месяцев. Мы также взаимодействовали с разработчиками небольших форков, которые, однако, решили злоупотребить этим (а вместе с этим и нашим доверием), немедленно став токсичными и пытаясь продать netc модуль "с полным античитом", который мы им дали, что побудило написать и в спешке опубликовать эту вики-статью. Нехорошо, и, пожалуйста, не ведитесь на предложения от упомянутого круга токсичных разработчиков форков, пытающихся продать вам такой netc "с полным античитом", когда вы можете получить более новую версию из официального источника, от нас в этой статье. Работа над этой статьёй в контексте упомянутого инцидента обсуждалась в MTA development discord (приглашение: https://discord.gg/GNN6PRtTnu) в этом посте: https://discord.com/channels/801330706252038164/801330706252038170/1044757943071023155 и аналогично в основном, официальном MTA discord (приглашение: https://discord.gg/mtasa) в этом посте: https://discord.com/channels/278474088903606273/278521065435824128/1044758439357849661

[[EN:Forks_Full_AC]]

RU/Полный античит MTA для форк-проектов

2023-03-15T17:50:01Z

Zver-CR:

__NOTOC__ {{Примечание|Информация на этой странице не относится к официальным сборкам MTA.}}

Форки MTA, которым недостаточно использовать "обычный netc для форков" (из bdata/netc.dll), как описано на вики-странице [[Forks]], из-за того, что он предлагает очень ограниченную античит-защиту, могут изучить возможности использования нового netc варианта: "полного античита для форков". Это, однако, имеет свои ограничения, относящиеся к особенностям вашего форк-проекта и реализации, которые нелегко объяснить, но эта страница стремится сделать это как можно точнее.

''Эта операция превратит ваш форк в проект с "надлежащим античитом, основанным на методе исправлений", как описано в спойлере в этой теме: https://forum.multitheftauto.com/topic/66858-bounty-for-finding-security-flaws-and-working-cheats-in-mta/, а не максимум 15% 'основанным на сигнатурах' античитом, как описано на вики-странице [[Forks]] для обычных форков.''

Основная идея:
* Модуль netc "с полным античитом для форков" будет предоставлять 95% функций античита, имеющихся в официальных MTA (multitheftauto.com > Кнопка "Download") сборках.
* Чем больше несовместимых функций/реализаций (пользовательских изменений) имеет ваш форк-проект, которые '''вы''' можете отключить (добавив их в белый список обнаружения: '''disableac''' массив в '''mtaserver.conf''', как описано на странице [https://wiki.multitheftauto.com/wiki/RU/Anti-cheat_guide#%3Cdisableac%3E%3C/disableac%3E Anti-cheat guide / Руководство по античиту: DISABLEAC]), тем ниже будет указанное число защиты в процентах.
** '''Например''', если вам нужно отключить 3 различных типа обнаружения (допустим, для российских форков, учитывая загрузку внешних модов вне MTA API/limit adjuster'а, наиболее распространёнными являются: 5, 6, 21), вы получите 85% оставшейся античит-защиты. Хотя это число относительно, так как это даёт разработчикам читов возможность использовать именно эти отключенные категории обнаружения для обеспечения работы их читов/хаков, и эти 3 кода уже предоставляют некоторые конкретные пути для записи в память GTA. 

Понимаете, к чему всё это идёт? Ниже в этой статье появится ссылка на "полный античит для форков", и то, что вы будете делать с ним - это метод проб и ошибок. Попытка интегрировать полную поддержку античита в ваш форк - это вопрос "Мы можем попробовать, и если это сработает, то будет здорово.. если нам придётся отключить некоторые обнаружения, то процент защиты будет выше, чем у обычного античита форков: 15% и это уже огромный выигрыш.." и во многом зависит от меры возможностей. Потому что причина, по которой мы разделили netc форков (из bdata/netc.dll) на тот, в котором отсутствует большинство античит-функций, может быть понятна любому опытному разработчику: netc-модуль (античит) не рассчитан на все типы настроек, которые разработчик форка может добавить в свою кодовую базу, это было сделано в духе предоставления максимальной свободы и гибкости. Тем более, что многие форки имеют не самых лучших разработчиков, не понимающих, почему им лучше следовать рекомендациям MTA (mtasa-blue) по написанию кода, структуре проекта и максимально приближать свои пользовательские реализации так, как это обычно делает участник MTA, прошедший проверку (ревью) кода. Таким образом, здесь происходит отделение 'чистых' изменений от 'грязного моддинга', который также часто встречается в российских форках, '''использующих один или несколько следующих подходов к кодовой базе своего проекта:
''' 

* Реализация моддинговых GTA: SA проектов внешним 'грязным' способом, как limit adjuster (fastman92 и т.д.)
* Необработанная (raw) загрузка модифицированных данных GTA: SA & .IMG файлов, через распространение предварительно модифицированных установочных папок GTA среди игроков форк клиента. Тем самым полностью игнорируя MTA API для замены моделей и различных игровых процессов.
* Различные грязные патчи, в широком смысле описанные в абзаце выше. Также включает в себя несоблюдение рекомендаций MTA по "Raw memory access" (необработанному доступу к памяти), найденных здесь: https://github.com/multitheftauto/mtasa-blue/wiki/Dev-Tips, что является значительным фактором риска для сценариев, не ожидаемых netc.dll (античитом), так как если он защищает от модификаций памяти, зная их происхождение, и вы просто поместите грязный 'writeProcessMemory' или memcpy в случайный .cpp файл, это вызовет нарушение. Это далеко не всё, и это плохой пример, но просто чтобы вы поняли, почему существуют несовместимости.

=== Получение максимального % античит-защиты ===

Поняв вышесказанное, а также то, что мы стараемся изо всех сил, так как такое использование в качестве "полного античита" для форков никогда не входило в наши планы, и что было бы трудно поддерживать пользовательские модификации каждого, вы можете понять, что мы не можем помочь вам выяснить, что является несовместимым сразу после того, как вы начнёте тестировать netc "с полным античитом" в своём форке. Поэтому вы сами должны либо отключить столько обнаружений, сколько требуется (если вы не можете их исправить - где 'не можете' является показателем отсутствия инженерного опыта), либо, что ещё лучше, разработать исправления, которые позволят вам избежать отключения слишком многих или любых типов обнаружения, тем самым максимизируя потенциальный % античит-функций.

Это означает, что без поддержки команды MTA вам предстоит выяснить, какие настройки/интеграции/несоблюдения MTA API/примеры проблем, описанные ранее в этой статье.. являются виновниками каждого конкретного типа обнаружения, который отправляет вам кики античита после добавления netc "с полным античитом" в ваш форк для тестирования. Мы советуем вам очистить свои интеграции, чтобы избежать необходимости много копаться вручную/выяснять виновника. Для этого обратите внимание на пункты маркированного списка из предыдущего абзаца. Однако, если же прямой виновник найден, приложив все свои усилия, вы должны без каких-либо указаний со стороны MTA придумать альтернативные (более чистые, более соответствующие рекомендациям MTA по написанию кода, API и структуре проекта.. следовательно, менее вероятно несовместимые с полным античитом и тем, что он ожидает) реализации проблемной настройки, найденной в кодовой базе вашего форка. Вы можете видеть, где возможность использовать 'полный античит для форков' становится скорее благосклонностью, чем данностью, особенно с тем состоянием кодовой базы, в котором многие форки, не начав свою разработку по сценарию 'полного античита', выросли, просто написав то, что работает для них, не учитывая такие аспекты. Общая картина того, почему мы не будем поддерживать процесс реинжиниринга, теперь должна быть ясна. Если вы не можете с этим справиться, либо наймите кого-то с большим опытом в компьютерных науках и инженерии, либо отключите больше типов обнаружения античита, и довольствуйтесь всем, что выше 15% обычного netc для форков, лучше что-то, чем ничего. '''Но мы не сможем протянуть руку помощи.''' Любое непонимание этих концепций указывает на отсутствие полноты разработчика (индивидуальных навыков, возможностей для роста) и не может быть отражено на разработчиках MTA.

= '''Давайте перейдём к делу''' =

Если вы считаете, что поняли все концепции, описанные в этой статье, вы можете приступить к внедрению "полного античита для форков":

'''СКАЧАЙТЕ: https://mirror-cdn.multitheftauto.com/bdata/fork-support/netc.dll''' (для использования ''вместо'' "bdata/netc.dll" из стандартного mtasa-blue buildactions/install_data.lua)
Обратите внимание, что версия netc.dll по указанной выше ссылке будет регулярно обновляться, чтобы предоставить форкам все античит-улучшения, поставляемые также и для официальной MTA. Поэтому рекомендуется регулярно получать обновления для вашего форка для обеспечения оптимальной безопасности & надёжности античита

{{Примечание|
* Важно: Начиная с января 2023 года, вы должны извлечь все коммиты (получить все изменения) mtasa-blue и синхронизировать кодовую базу вашего форка, чтобы использовать последнюю версию netc, представленную по ссылке выше. Существуют несовместимые изменения, которые требуют обновления с обеих сторон. // '''ОБНОВЛЕНИЕ''': Это произошло снова в марте 2023 года, теперь вам необходимо получить как минимум r21618 (коммит eedbdc5fbfdd5d5bed8454728d8e224a4b94838e в mtasa-blue git'е), чтобы использовать версию модуля netc.dll, предлагаемую на данный момент.
}}
{{Примечание|
* Важно: Вы сами несёте ответственность за добавление средства проверки целостности/подлинности файлов, так как очевидно, что поскольку игровые DLL собираются вами (а не нами), нет возможности внедрить такие уникальные DLL в наши внутренние контрольные списки netc, равно как и нет ничего в других модулях для проверки самого netc. Если вы не доработаете это, читер может просто заменить любой модуль или добавить читерскую полезную нагрузку (payload) с помощью редактирования PE, это самый большой фактор риска при использовании "полного античита для форков". Как далеко вы хотели бы зайти с проверкой файлов, например, решить усилить её в пользовательском режиме (usermode) (с heartbeat'ами или около того) или использовать режим ядра (kernelmode), зависит от вас и уровня приверженности безопасности вашего проекта. Если всё, что вас волнует, это небольшая преграда в отношении читерства, вы можете использовать базовую проверку файлов (MD5/SHA256) для всех игровых модулей
}}

- Замените netc.dll в вашем форк-проекте на вышеуказанный "поддерживаемый для форков" netc с полным античитом.
- Убедитесь, что тип сборки в version.h изменён на UNSTABLE, согласно рекомендациям "массового потребления" для форков в комментариях: [https://github.com/multitheftauto/mtasa-blue/blob/master/Shared/sdk/version.h Shared/sdk/version.h]. В противном случае, вы сведёте на нет все усилия по получению полной античит-защиты.

- Убедитесь, что вы обновили кодовую базу вашего форка до активной основной версии (для которой netc.dll), '''мастер'''-коммита mtasa-blue, по крайней мере до версии "Default", указанной на [https://nightly.mtasa.com/ver/] как "Auto-update default" для последней основной версии, затем сопоставьте указанную ревизию с SHA1-хешем коммита с помощью этого инструмента: https://buildinfo.mtasa.com/index.php - это означает, что не следует использовать начальный выпуск (версию, которая имеет метку выпуска на github), потому что MTA использует модель "MTA как услуга", где игроки получают регулярные обновления, содержащие все основные изменения для оптимального качества и опыта использования новых функций. Последние выпуски netc.dll основаны на этом и могут требовать присутствия мастер-изменений.

- Столкнитесь с некоторыми киками античита в вашем форк-клиенте, этап проб и ошибок начинается здесь. Теперь используйте предыдущие части этого руководства, чтобы либо отключить типы обнаружения античита с помощью disableac в mtaserver.conf, либо, что ещё лучше, потратьте больше сил разработчиков на правильное исправление & очистку ваших пользовательских реализаций, как советовали ранее, чтобы сохранить как можно больше % античит-защиты. Мы советуем не опускаться ниже 85% (как в примере с 'disableac' кодами: 5, 6, 21 было упомянуто, что это относительно 85% и то, что требуется большинству российских тяжёлых модифицированных форков для немедленного запуска и возможности вам подключиться).

Заключительные слова: всегда будет лучше не быть форком в первую очередь. Используйте официальный клиент MTA и просто создайте сервер, со временем со своим пользовательским лаунчером, который будет подключать непосредственно к вашему ряду серверов. Просто внесите все настройки, которые вам нужны (причина для создания форка), взяв за основу "upstream" и создайте PR, Pull request (пул-реквест), используя официальный репозиторий MTA https://github.com/multitheftauto/mtasa-blue, чтобы все выиграли, а вы соблюдали лицензию & не сталкивались с препятствиями, включая античит и приток новых игроков, которые возникают при создании форка. MTA обычно имеет 30000 игроков онлайн одновременно, что также является огромным притоком новых игроков для открытия своего сообщества. Лучше просто не быть форком, но если вам действительно нужно, эта страница является нашим активным взаимодействием с форками для получения лучшего уровня античит-защиты. 
Мы создали этот вариант netc.dll "с полным античитом для форков" в ноябре/декабре 2022 года и опробовали практические результаты и некоторые специфические исправления для лучшей поддержки, с 2 крупнейшими российскими MTA форками, оба из которых готовятся выпустить обновление, включающее это в ближайшие несколько месяцев. Мы также взаимодействовали с разработчиками небольших форков, которые, однако, решили злоупотребить этим (а вместе с этим и нашим доверием), немедленно став токсичными и пытаясь продать netc-модуль "с полным античитом", который мы им дали, что побудило написать и в спешке опубликовать эту вики-статью. Нехорошо, и, пожалуйста, не ведитесь на предложения от упомянутого круга токсичных разработчиков форков, пытающихся продать вам такой netc "с полным античитом", когда вы можете получить более новую версию из официального источника, от нас в этой статье. Работа над этой статьёй в контексте упомянутого инцидента обсуждалась в MTA development discord (приглашение: https://discord.gg/GNN6PRtTnu) в этом посте: https://discord.com/channels/801330706252038164/801330706252038170/1044757943071023155 и аналогично в основном, официальном MTA discord (приглашение: https://discord.gg/mtasa) в этом посте: https://discord.com/channels/278474088903606273/278521065435824128/1044758439357849661

[[EN:Forks_Full_AC]]

RU/Полный античит MTA для форк-проектов

2023-02-02T00:45:59Z

Zver-CR:

__NOTOC__ {{Примечание|Информация на этой странице не относится к официальным сборкам MTA.}}
__NOTOC__ {{Примечание|Это не окончательная версия этой страницы, она будет улучшаться/дополняться/переписываться.}}

Форки MTA, которым недостаточно использовать "обычный netc для форков" (из bdata/netc.dll), как описано на вики-странице [[Forks]], из-за того, что он предлагает очень ограниченную античит-защиту, могут изучить возможности использования нового netc варианта: "полного античита для форков". Это, однако, имеет свои ограничения, относящиеся к особенностям вашего форк-проекта и реализации, которые нелегко объяснить, но эта страница стремится сделать это как можно точнее.

''Эта операция превратит ваш форк в проект с "надлежащим античитом, основанным на методе исправлений", как описано в спойлере в этой теме: https://forum.multitheftauto.com/topic/66858-bounty-for-finding-security-flaws-and-working-cheats-in-mta/, а не максимум 15% 'основанным на сигнатурах' античитом, как описано на вики-странице [[Forks]] для обычных форков.''

Основная идея:
* Модуль netc "с полным античитом для форков" будет предоставлять 95% функций античита, имеющихся в официальных MTA (multitheftauto.com > Кнопка "Download") сборках.
* Чем больше несовместимых функций/реализаций (пользовательских изменений) имеет ваш форк-проект, которые '''вы''' можете отключить (добавив их в белый список обнаружения: '''disableac''' массив в '''mtaserver.conf''', как описано на странице [https://wiki.multitheftauto.com/wiki/RU/Anti-cheat_guide#%3Cdisableac%3E%3C/disableac%3E Anti-cheat guide / Руководство по античиту: DISABLEAC]), тем ниже будет указанное число защиты в процентах.
** '''Например''', если вам нужно отключить 3 различных типа обнаружения (допустим, для российских форков, учитывая загрузку внешних модов вне MTA API/limit adjuster'а, наиболее распространёнными являются: 5, 6, 21), вы получите 85% оставшейся античит-защиты. Хотя это число относительно, так как это даёт разработчикам читов возможность использовать именно эти отключенные категории обнаружения для обеспечения работы их читов/хаков, и эти 3 кода уже предоставляют некоторые конкретные пути для записи в память GTA. 

Понимаете, к чему всё это идёт? Ниже в этой статье появится ссылка на "полный античит для форков", и то, что вы будете делать с ним - это метод проб и ошибок. Попытка интегрировать полную поддержку античита в ваш форк - это вопрос "Мы можем попробовать, и если это сработает, то будет здорово.. если нам придётся отключить некоторые обнаружения, то процент защиты будет выше, чем у обычного античита форков: 15% и это уже огромный выигрыш.." и во многом зависит от меры возможностей. Потому что причина, по которой мы разделили netc форков (из bdata/netc.dll) на тот, в котором отсутствует большинство античит-функций, может быть понятна любому опытному разработчику: netc-модуль (античит) не рассчитан на все типы настроек, которые разработчик форка может добавить в свою кодовую базу, это было сделано в духе предоставления максимальной свободы и гибкости. Тем более, что многие форки имеют не самых лучших разработчиков, не понимающих, почему им лучше следовать рекомендациям MTA (mtasa-blue) по написанию кода, структуре проекта и максимально приближать свои пользовательские реализации так, как это обычно делает участник MTA, прошедший проверку (ревью) кода. Таким образом, здесь происходит отделение 'чистых' изменений от 'грязного моддинга', который также часто встречается в российских форках, '''использующих один или несколько следующих подходов к кодовой базе своего проекта:
''' 

* Реализация моддинговых GTA: SA проектов внешним 'грязным' способом, как limit adjuster (fastman92 и т.д.)
* Необработанная (raw) загрузка модифицированных данных GTA: SA & .IMG файлов, через распространение предварительно модифицированных установочных папок GTA среди игроков форк клиента. Тем самым полностью игнорируя MTA API для замены моделей и различных игровых процессов.
* Различные грязные патчи, в широком смысле описанные в абзаце выше. Также включает в себя несоблюдение рекомендаций MTA по "Raw memory access" (необработанному доступу к памяти), найденных здесь: https://github.com/multitheftauto/mtasa-blue/wiki/Dev-Tips, что является значительным фактором риска для сценариев, не ожидаемых netc.dll (античитом), так как если он защищает от модификаций памяти, зная их происхождение, и вы просто поместите грязный 'writeProcessMemory' или memcpy в случайный .cpp файл, это вызовет нарушение. Это далеко не всё, и это плохой пример, но просто чтобы вы поняли, почему существуют несовместимости.

=== Получение максимального % античит-защиты ===

Поняв вышесказанное, а также то, что мы стараемся изо всех сил, так как такое использование в качестве "полного античита" для форков никогда не входило в наши планы, и что было бы трудно поддерживать пользовательские модификации каждого, вы можете понять, что мы не можем помочь вам выяснить, что является несовместимым сразу после того, как вы начнёте тестировать netc "с полным античитом" в своём форке. Поэтому вы сами должны либо отключить столько обнаружений, сколько требуется (если вы не можете их исправить - где 'не можете' является показателем отсутствия инженерного опыта), либо, что ещё лучше, разработать исправления, которые позволят вам избежать отключения слишком многих или любых типов обнаружения, тем самым максимизируя потенциальный % античит-функций.

Это означает, что без поддержки команды MTA вам предстоит выяснить, какие настройки/интеграции/несоблюдения MTA API/примеры проблем, описанные ранее в этой статье.. являются виновниками каждого конкретного типа обнаружения, который отправляет вам кики античита после добавления netc "с полным античитом" в ваш форк для тестирования. Мы советуем вам очистить свои интеграции, чтобы избежать необходимости много копаться вручную/выяснять виновника. Для этого обратите внимание на пункты маркированного списка из предыдущего абзаца. Однако, если же прямой виновник найден, приложив все свои усилия, вы должны без каких-либо указаний со стороны MTA придумать альтернативные (более чистые, более соответствующие рекомендациям MTA по написанию кода, API и структуре проекта.. следовательно, менее вероятно несовместимые с полным античитом и тем, что он ожидает) реализации проблемной настройки, найденной в кодовой базе вашего форка. Вы можете видеть, где возможность использовать 'полный античит для форков' становится скорее благосклонностью, чем данностью, особенно с тем состоянием кодовой базы, в котором многие форки, не начав свою разработку по сценарию 'полного античита', выросли, просто написав то, что работает для них, не учитывая такие аспекты. Общая картина того, почему мы не будем поддерживать процесс реинжиниринга, теперь должна быть ясна. Если вы не можете с этим справиться, либо наймите кого-то с большим опытом в компьютерных науках и инженерии, либо отключите больше типов обнаружения античита, и довольствуйтесь всем, что выше 15% обычного netc для форков, лучше что-то, чем ничего. '''Но мы не сможем протянуть руку помощи.''' Любое непонимание этих концепций указывает на отсутствие полноты разработчика (индивидуальных навыков, возможностей для роста) и не может быть отражено на разработчиках MTA.

= '''Давайте перейдём к делу''' =

Если вы считаете, что поняли все концепции, описанные в этой статье, вы можете приступить к внедрению "полного античита для форков":

'''СКАЧАЙТЕ: https://mirror-cdn.multitheftauto.com/bdata/fork-support/netc.dll''' (для использования ''вместо'' "bdata/netc.dll" из стандартного mtasa-blue buildactions/install_data.lua)
Обратите внимание, что версия netc.dll по указанной выше ссылке будет регулярно обновляться, чтобы предоставить форкам все античит-улучшения, поставляемые также и для официальной MTA. Поэтому рекомендуется регулярно получать обновления для вашего форка для обеспечения оптимальной безопасности & надёжности античита

{{Примечание|
* Важно: Начиная с января 2023 года, вы должны извлечь все коммиты (получить все изменения) mtasa-blue и синхронизировать кодовую базу вашего форка, чтобы использовать последнюю версию netc, представленную по ссылке выше. Существуют несовместимые изменения, которые требуют обновления с обеих сторон
}}
{{Примечание|
* Важно: Вы сами несёте ответственность за добавление средства проверки целостности/подлинности файлов, так как очевидно, что поскольку игровые DLL собираются вами (а не нами), нет возможности внедрить такие уникальные DLL в наши внутренние контрольные списки netc, равно как и нет ничего в других модулях для проверки самого netc. Если вы не доработаете это, читер может просто заменить любой модуль или добавить читерскую полезную нагрузку (payload) с помощью редактирования PE, это самый большой фактор риска при использовании "полного античита для форков". Как далеко вы хотели бы зайти с проверкой файлов, например, решить усилить её в пользовательском режиме (usermode) (с heartbeat'ами или около того) или использовать режим ядра (kernelmode), зависит от вас и уровня приверженности безопасности вашего проекта. Если всё, что вас волнует, это небольшая преграда в отношении читерства, вы можете использовать базовую проверку файлов (MD5/SHA256) для всех игровых модулей
}}

- Замените netc.dll в вашем форк-проекте на вышеуказанный "поддерживаемый для форков" netc с полным античитом.
- Убедитесь, что тип сборки в version.h изменён на UNSTABLE, согласно рекомендациям "массового потребления" для форков в комментариях: [https://github.com/multitheftauto/mtasa-blue/blob/master/Shared/sdk/version.h Shared/sdk/version.h]. В противном случае, вы сведёте на нет все усилия по получению полной античит-защиты.

- Убедитесь, что вы обновили кодовую базу вашего форка до активной основной версии (для которой netc.dll), '''мастер'''-коммита mtasa-blue, по крайней мере до версии "Default", указанной на [https://nightly.mtasa.com/ver/] как "Auto-update default" для последней основной версии, затем сопоставьте указанную ревизию с SHA1-хешем коммита с помощью этого инструмента: https://buildinfo.mtasa.com/index.php - это означает, что не следует использовать начальный выпуск (версию, которая имеет метку выпуска на github), потому что MTA использует модель "MTA как услуга", где игроки получают регулярные обновления, содержащие все основные изменения для оптимального качества и опыта использования новых функций. Последние выпуски netc.dll основаны на этом и могут требовать присутствия мастер-изменений.

- Столкнитесь с некоторыми киками античита в вашем форк-клиенте, этап проб и ошибок начинается здесь. Теперь используйте предыдущие части этого руководства, чтобы либо отключить типы обнаружения античита с помощью disableac в mtaserver.conf, либо, что ещё лучше, потратьте больше сил разработчиков на правильное исправление & очистку ваших пользовательских реализаций, как советовали ранее, чтобы сохранить как можно больше % античит-защиты. Мы советуем не опускаться ниже 85% (как в примере с 'disableac' кодами: 5, 6, 21 было упомянуто, что это относительно 85% и то, что требуется большинству российских тяжёлых модифицированных форков для немедленного запуска и возможности вам подключиться).

Заключительные слова: всегда будет лучше не быть форком в первую очередь. Используйте официальный клиент MTA и просто создайте сервер, со временем со своим пользовательским лаунчером, который будет подключать непосредственно к вашему ряду серверов. Просто внесите все настройки, которые вам нужны (причина для создания форка), взяв за основу "upstream" и создайте PR, Pull request (пул-реквест), используя официальный репозиторий MTA https://github.com/multitheftauto/mtasa-blue, чтобы все выиграли, а вы соблюдали лицензию & не сталкивались с препятствиями, включая античит и приток новых игроков, которые возникают при создании форка. MTA обычно имеет 30000 игроков онлайн одновременно, что также является огромным притоком новых игроков для открытия своего сообщества. Лучше просто не быть форком, но если вам действительно нужно, эта страница является нашим активным взаимодействием с форками для получения лучшего уровня античит-защиты. 
Мы создали этот вариант netc.dll "с полным античитом для форков" в ноябре/декабре 2022 года и опробовали практические результаты и некоторые специфические исправления для лучшей поддержки, с 2 крупнейшими российскими MTA форками, оба из которых готовятся выпустить обновление, включающее это в ближайшие несколько месяцев. Мы также взаимодействовали с разработчиками небольших форков, которые, однако, решили злоупотребить этим (а вместе с этим и нашим доверием), немедленно став токсичными и пытаясь продать netc-модуль "с полным античитом", который мы им дали, что побудило написать и в спешке опубликовать эту вики-статью. Нехорошо, и, пожалуйста, не ведитесь на предложения от упомянутого круга токсичных разработчиков форков, пытающихся продать вам такой netc "с полным античитом", когда вы можете получить более новую версию из официального источника, от нас в этой статье. Работа над этой статьёй в контексте упомянутого инцидента обсуждалась в MTA development discord (приглашение: https://discord.gg/GNN6PRtTnu) в этом посте: https://discord.com/channels/801330706252038164/801330706252038170/1044757943071023155 и аналогично в основном, официальном MTA discord (приглашение: https://discord.gg/mtasa) в этом посте: https://discord.com/channels/278474088903606273/278521065435824128/1044758439357849661

[[EN:Forks_Full_AC]]

RU/Полный античит MTA для форк-проектов

2023-02-02T00:37:50Z

Zver-CR:

__NOTOC__ {{Примечание|Информация на этой странице не относится к официальным сборкам MTA.}}
__NOTOC__ {{Примечание|Это не окончательная версия этой страницы, она будет улучшаться/дополняться/переписываться.}}

Форки MTA, которым недостаточно использовать "обычный netc для форков" (из bdata/netc.dll), как описано на вики-странице [[Forks]], из-за того, что он предлагает очень ограниченную античит-защиту, могут изучить возможности использования нового netc варианта: "полного античита для форков". Это, однако, имеет свои ограничения, относящиеся к особенностям вашего форк-проекта и реализации, которые нелегко объяснить, но эта страница стремится сделать это как можно точнее.

''Эта операция превратит ваш форк в проект с "надлежащим античитом, основанным на методе исправлений", как описано в спойлере в этой теме: https://forum.multitheftauto.com/topic/66858-bounty-for-finding-security-flaws-and-working-cheats-in-mta/, а не максимум 15% 'основанным на сигнатурах' античитом, как описано на вики-странице [[Forks]] для обычных форков.''

Основная идея:
* Модуль netc "с полным античитом для форков" будет предоставлять 95% функций античита, имеющихся в официальных MTA (multitheftauto.com > Кнопка "Download") сборках.
* Чем больше несовместимых функций/реализаций (пользовательских изменений) имеет ваш форк-проект, которые '''вы''' можете отключить (добавив их в белый список обнаружения: '''disableac''' массив в '''mtaserver.conf''', как описано на странице [https://wiki.multitheftauto.com/wiki/RU/Anti-cheat_guide#%3Cdisableac%3E%3C/disableac%3E Anti-cheat guide / Руководство по античиту: DISABLEAC]), тем ниже будет указанное число защиты в процентах.
** '''Например''', если вам нужно отключить 3 различных типа обнаружения (допустим, для российских форков, учитывая загрузку внешних модов вне MTA API/limit adjuster'а, наиболее распространёнными являются: 5, 6, 21), вы получите 85% оставшейся античит-защиты. Хотя это число относительно, так как это даёт разработчикам читов возможность использовать именно эти отключенные категории обнаружения для обеспечения работы их читов/хаков, и эти 3 кода уже предоставляют некоторые конкретные пути для записи в память GTA. 

Понимаете, к чему всё это идёт? Ниже в этой статье появится ссылка на "полный античит для форков", и то, что вы будете делать с ним - это метод проб и ошибок. Попытка интегрировать полную поддержку античита в ваш форк - это вопрос "Мы можем попробовать, и если это сработает, то будет здорово.. если нам придётся отключить некоторые обнаружения, то процент защиты будет выше, чем у обычного античита форков: 15% и это уже огромный выигрыш.." и во многом зависит от меры возможностей. Потому что причина, по которой мы разделили netc форков (из bdata/netc.dll) на тот, в котором отсутствует большинство античит-функций, может быть понятна любому опытному разработчику: netc-модуль (античит) не рассчитан на все типы настроек, которые разработчик форка может добавить в свою кодовую базу, это было сделано в духе предоставления максимальной свободы и гибкости. Тем более, что многие форки имеют не самых лучших разработчиков, не понимающих, почему им лучше следовать рекомендациям MTA (mtasa-blue) по написанию кода, структуре проекта и максимально приближать свои пользовательские реализации так, как это обычно делает участник MTA, прошедший проверку (ревью) кода. Таким образом, здесь происходит отделение 'чистых' изменений от 'грязного моддинга', который также часто встречается в российских форках, '''использующих один или несколько следующих подходов к кодовой базе своего проекта:
''' 

* Реализация моддинговых GTA: SA проектов внешним 'грязным' способом, как limit adjuster (fastman92 и т.д.)
* Необработанная (raw) загрузка модифицированных данных GTA: SA & .IMG файлов, через распространение предварительно модифицированных установочных папок GTA среди игроков форк клиента. Тем самым полностью игнорируя MTA API для замены моделей и различных игровых процессов.
* Различные грязные патчи, в широком смысле описанные в абзаце выше. Также включает в себя несоблюдение рекомендаций MTA по "Raw memory access" (необработанному доступу к памяти), найденных здесь: https://github.com/multitheftauto/mtasa-blue/wiki/Dev-Tips, что является значительным фактором риска для сценариев, не ожидаемых netc.dll (античитом), так как если он защищает от модификаций памяти, зная их происхождение, и вы просто поместите грязный 'writeProcessMemory' или memcpy в случайный .cpp файл, это вызовет нарушение. Это далеко не всё, и это плохой пример, но просто чтобы вы поняли, почему существуют несовместимости.

=== Получение максимального % античит-защиты ===

Поняв вышесказанное, а также то, что мы стараемся изо всех сил, так как такое использование в качестве "полного античита" для форков никогда не входило в наши планы, и что было бы трудно поддерживать пользовательские модификации каждого, вы можете понять, что мы не можем помочь вам выяснить, что является несовместимым сразу после того, как вы начнёте тестировать netc "с полным античитом" в своём форке. Поэтому вы сами должны либо отключить столько обнаружений, сколько требуется (если вы не можете их исправить - где 'не можете' является показателем отсутствия инженерного опыта), либо, что ещё лучше, разработать исправления, которые позволят вам избежать отключения слишком многих или любых типов обнаружения, тем самым максимизируя потенциальный % античит-функций.

Это означает, что без поддержки команды MTA вам предстоит выяснить, какие настройки/интеграции/несоблюдения MTA API/примеры проблем, описанные ранее в этой статье.. являются виновниками каждого конкретного типа обнаружения, который отправляет вам кики античита после добавления netc "с полным античитом" в ваш форк для тестирования. Мы советуем вам очистить свои интеграции, чтобы избежать необходимости много копаться вручную/выяснять виновника. Для этого обратите внимание на пункты маркированного списка из предыдущего абзаца. Однако, если же прямой виновник найден, приложив все свои усилия, вы должны без каких-либо указаний со стороны MTA придумать альтернативные (более чистые, более соответствующие рекомендациям MTA по написанию кода, API и структуре проекта.. следовательно, менее вероятно несовместимые с полным античитом и тем, что он ожидает) реализации проблемной настройки, найденной в кодовой базе вашего форка. Вы можете видеть, где возможность использовать 'полный античит для форков' становится скорее благосклонностью, чем данностью, особенно с тем состоянием кодовой базы, в котором многие форки, не начав свою разработку по сценарию 'полного античита', выросли, просто написав то, что работает для них, не учитывая такие аспекты. Общая картина того, почему мы не будем поддерживать процесс реинжиниринга, теперь должна быть ясна. Если вы не можете с этим справиться, либо наймите кого-то с большим опытом в компьютерных науках и инженерии, либо отключите больше типов обнаружения античита, и довольствуйтесь всем, что выше 15% обычного netc для форков, лучше что-то, чем ничего. '''Но мы не сможем протянуть руку помощи.''' Любое непонимание этих концепций указывает на отсутствие полноты разработчика (индивидуальных навыков, возможностей для роста) и не может быть отражено на разработчиках MTA.

= '''Давайте перейдём к делу''' =

Если вы считаете, что поняли все концепции, описанные в этой статье, вы можете приступить к внедрению "полного античита для форков":

'''СКАЧАЙТЕ: https://mirror-cdn.multitheftauto.com/bdata/fork-support/netc.dll''' (для использования ''вместо'' "bdata/netc.dll" из стандартного mtasa-blue buildactions/install_data.lua)
Обратите внимание, что версия netc.dll по указанной выше ссылке будет регулярно обновляться, чтобы предоставить форкам все античит-улучшения, поставляемые также и для официальной MTA. Поэтому рекомендуется регулярно получать обновления для вашего форка для обеспечения оптимальной безопасности & надёжности античита

{{Примечание|
* Важно: Начиная с января 2023 года, вы должны извлечь все коммиты (получить все изменения) mtasa-blue и синхронизировать кодовую базу вашего форка, чтобы использовать последнюю версию netc, представленную по ссылке выше. Существуют несовместимые изменения, которые требуют обновления с обеих сторон
}}
{{Примечание|
* Важно: Вы сами несёте ответственность за добавление средства проверки целостности/подлинности файлов, так как очевидно, что поскольку игровые DLL собираются вами (а не нами), нет возможности внедрить такие уникальные DLL в наши внутренние контрольные списки netc, равно как и нет ничего в других модулях для проверки самого netc. Если вы не доработаете это, читер может просто заменить любой модуль или добавить в чит полезную нагрузку (payload) с помощью редактирования PE, это самый большой фактор риска при использовании "полного античита для форков". Как далеко вы хотели бы зайти с проверкой файлов, например, решить усилить её в пользовательском режиме (usermode) (с heartbeat'ами или около того) или использовать режим ядра (kernelmode), зависит от вас и уровня приверженности безопасности вашего проекта. Если всё, что вас волнует, это небольшая преграда в отношении читерства, вы можете использовать базовую проверку файлов (MD5/SHA256) для всех игровых модулей
}}

- Замените netc.dll в вашем форк-проекте на вышеуказанный "поддерживаемый для форков" netc с полным античитом.
- Убедитесь, что тип сборки в version.h изменён на UNSTABLE, согласно рекомендациям "массового потребления" для форков в комментариях: [https://github.com/multitheftauto/mtasa-blue/blob/master/Shared/sdk/version.h Shared/sdk/version.h]. В противном случае, вы сведёте на нет все усилия по получению полной античит-защиты.

- Убедитесь, что вы обновили кодовую базу вашего форка до активной основной версии (для которой netc.dll), '''мастер'''-коммита mtasa-blue, по крайней мере до версии "Default", указанной на [https://nightly.mtasa.com/ver/] как "Auto-update default" для последней основной версии, затем сопоставьте указанную ревизию с SHA1-хешем коммита с помощью этого инструмента: https://buildinfo.mtasa.com/index.php - это означает, что не следует использовать начальный выпуск (версию, которая имеет метку выпуска на github), потому что MTA использует модель "MTA как услуга", где игроки получают регулярные обновления, содержащие все основные изменения для оптимального качества и опыта использования новых функций. Последние выпуски netc.dll основаны на этом и могут требовать присутствия мастер-изменений.

- Столкнитесь с некоторыми киками античита в вашем форк-клиенте, этап проб и ошибок начинается здесь. Теперь используйте предыдущие части этого руководства, чтобы либо отключить типы обнаружения античита с помощью disableac в mtaserver.conf, либо, что ещё лучше, потратьте больше сил разработчиков на правильное исправление & очистку ваших пользовательских реализаций, как советовали ранее, чтобы сохранить как можно больше % античит-защиты. Мы советуем не опускаться ниже 85% (как в примере с 'disableac' кодами: 5, 6, 21 было упомянуто, что это относительно 85% и то, что требуется большинству российских тяжёлых модифицированных форков для немедленного запуска и возможности вам подключиться).

Заключительные слова: всегда будет лучше не быть форком в первую очередь. Используйте официальный клиент MTA и просто создайте сервер, со временем со своим пользовательским лаунчером, который будет подключать непосредственно к вашему ряду серверов. Просто внесите все настройки, которые вам нужны (причина для создания форка), взяв за основу "upstream" и создайте PR, Pull request (пул-реквест), используя официальный репозиторий MTA https://github.com/multitheftauto/mtasa-blue, чтобы все выиграли, а вы соблюдали лицензию & не сталкивались с препятствиями, включая античит и приток новых игроков, которые возникают при создании форка. MTA обычно имеет 30000 игроков онлайн одновременно, что также является огромным притоком новых игроков для открытия своего сообщества. Лучше просто не быть форком, но если вам действительно нужно, эта страница является нашим активным взаимодействием с форками для получения лучшего уровня античит-защиты. 
Мы создали этот вариант netc.dll "с полным античитом для форков" в ноябре/декабре 2022 года и опробовали практические результаты и некоторые специфические исправления для лучшей поддержки, с 2 крупнейшими российскими MTA форками, оба из которых готовятся выпустить обновление, включающее это в ближайшие несколько месяцев. Мы также взаимодействовали с разработчиками небольших форков, которые, однако, решили злоупотребить этим (а вместе с этим и нашим доверием), немедленно став токсичными и пытаясь продать netc-модуль "с полным античитом", который мы им дали, что побудило написать и в спешке опубликовать эту вики-статью. Нехорошо, и, пожалуйста, не ведитесь на предложения от упомянутого круга токсичных разработчиков форков, пытающихся продать вам такой netc "с полным античитом", когда вы можете получить более новую версию из официального источника, от нас в этой статье. Работа над этой статьёй в контексте упомянутого инцидента обсуждалась в MTA development discord (приглашение: https://discord.gg/GNN6PRtTnu) в этом посте: https://discord.com/channels/801330706252038164/801330706252038170/1044757943071023155 и аналогично в основном, официальном MTA discord (приглашение: https://discord.gg/mtasa) в этом посте: https://discord.com/channels/278474088903606273/278521065435824128/1044758439357849661

[[EN:Forks_Full_AC]]

RU/How to repair the database files

2022-12-26T23:36:24Z

Zver-CR:

=Может быть, все в порядке=
Бывают ситуации, когда не о чем беспокоиться. Ответьте на следующие вопросы:
* Пришли ли вы на эту страницу из-за увиденного сообщения в консоли сервера или логах?
* Есть ли следующий текст в начале блока сообщений-ошибок?
ERROR: near "3": syntax error
* Если это так, то все OK. Вам не нужно делать ничего из описанного ниже, а ошибку можно смело проигнорировать.

=Предупреждения=
'''Сделайте резервные копии всех файлов перед попыткой восстановления!'''
 
'''Выключите сервер перед восстановлением!'''

=Windows=

==Простой способ==
*Скачайте [https://mirror-cdn.multitheftauto.com/files/mtasa-db-repair-win.zip это]
*Распакуйте архив и положите файлы по пути ''server/mods/deathmatch/''
*Дважды кликните по ''sqlite_repair_internal_db.bat'', чтобы восстановить internal.db
*Дважды кликните по ''sqlite_repair_registry_db.bat'', чтобы восстановить registry.db

==Сложный способ==

*Скачайте sqlite-tools-win32 [https://www.sqlite.org/2022/sqlite-tools-win32-x86-3400000.zip отсюда]. Если ссылка не сработает, главная страница закачки [https://www.sqlite.org/download.html здесь].
*Распакуйте архив и поместите sqlite3.exe в ''server/mods/deathmatch/''
*Откройте командную строку и перейдите в папку ''server/mods/deathmatch/''
*Чтобы восстановить internal.db:
**Скопируйте '''internal.db''', переименовав в '''internal_original.db'''
**Пропишите следующую команду: '''sqlite3.exe internal_original.db .dump | sqlite3.exe internal_repaired.db'''
**Скопируйте '''internal_repaired.db''', переименовав в '''internal.db'''

*Чтобы восстановить registry.db:
**Скопируйте '''registry.db''', переименовав в '''registry_original.db'''
**Пропишите следующую команду: '''sqlite3.exe registry_original.db .dump | sqlite3.exe registry_repaired.db'''
**Скопируйте '''registry_repaired.db''', переименовав в '''registry.db'''

=Linux=

==Единственный способ==
(Вы можете воспользоваться простым способом, скопировав БД из linux в windows, а затем воспользовавшись методами для компьютеров с windows)
*Скачайте sqlite-tools-linux-x86 [https://www.sqlite.org/2022/sqlite-tools-linux-x86-3400000.zip отсюда]. Если ссылка не сработает, главная страница закачки [https://www.sqlite.org/download.html здесь].
*Распакуйте архив и поместите sqlite3 в ''server/mods/deathmatch/''
*Чтобы восстановить internal.db:
**Скопируйте '''internal.db''', переименовав в '''internal_original.db'''
**Пропишите следующую команду: '''./sqlite3 internal_original.db .dump | ./sqlite3 internal_repaired.db'''
**Скопируйте '''internal_repaired.db''', переименовав в '''internal.db'''
<section name="Commands" class="server" show="false">
<syntaxhighlight lang="lua">
cp internal.db internal_original.db
./sqlite3 internal_original.db .dump | ./sqlite3 internal_repaired.db
cp internal_repaired.db internal.db
</syntaxhighlight>
</section>

*Чтобы восстановить registry.db:
**Скопируйте '''registry.db''', переименовав в '''registry_original.db'''
**Пропишите следующую команду: '''./sqlite3 registry_original.db .dump | ./sqlite3 registry_repaired.db'''
**Скопируйте '''registry_repaired.db''', переименовав в '''registry.db'''
<section name="Commands" class="server" show="false">
<syntaxhighlight lang="lua">
cp registry.db registry_original.db
./sqlite3 registry_original.db .dump | ./sqlite3 registry_repaired.db
cp registry_repaired.db registry.db
</syntaxhighlight>
</section>

[[Category:Поддержка]]
[[en:How to repair the database files]]

RU/Полный античит MTA для форк-проектов

2022-12-19T08:03:08Z

Zver-CR:

__NOTOC__ {{Примечание|Информация на этой странице не относится к официальным сборкам MTA.}}
__NOTOC__ {{Примечание|Это не окончательная версия этой страницы, она будет улучшаться/дополняться/переписываться.}}

Форки MTA, которым недостаточно использовать "обычный netc для форков" (из bdata/netc.dll), как описано на вики-странице [[Forks]], из-за того, что он предлагает очень ограниченную античит-защиту, могут изучить возможности использования нового netc варианта: "полного античита для форков". Это, однако, имеет свои ограничения, относящиеся к особенностям вашего форк-проекта и реализации, которые нелегко объяснить, но эта страница стремится сделать это как можно точнее.

''Эта операция превратит ваш форк в проект с "надлежащим античитом, основанным на методе исправлений", как описано в спойлере в этой теме: https://forum.multitheftauto.com/topic/66858-bounty-for-finding-security-flaws-and-working-cheats-in-mta/, а не максимум 15% 'основанным на сигнатурах' античитом, как описано на вики-странице [[Forks]] для обычных форков.''

Основная идея:
* Модуль netc "с полным античитом для форков" будет предоставлять 95% функций античита, имеющихся в официальных MTA (multitheftauto.com > Кнопка "Download") сборках.
* Чем больше несовместимых функций/реализаций (пользовательских изменений) имеет ваш форк-проект, которые '''вы''' можете отключить (добавив их в белый список обнаружения: '''disableac''' массив в '''mtaserver.conf''', как описано на странице [https://wiki.multitheftauto.com/wiki/RU/Anti-cheat_guide#%3Cdisableac%3E%3C/disableac%3E Anti-cheat guide / Руководство по античиту: DISABLEAC]), тем ниже будет указанное число защиты в процентах.
** '''Например''', если вам нужно отключить 3 различных типа обнаружения (допустим, для российских форков, учитывая загрузку внешних модов вне MTA API/limit adjuster'а, наиболее распространёнными являются: 5, 6, 21), вы получите 85% оставшейся античит-защиты. Хотя это число относительно, так как это даёт разработчикам читов возможность использовать именно эти отключенные категории обнаружения для обеспечения работы их читов/хаков, и эти 3 кода уже предоставляют некоторые конкретные пути для записи в память GTA. 

Понимаете, к чему всё это идёт? Ниже в этой статье появится ссылка на "полный античит для форков", и то, что вы будете делать с ним - это метод проб и ошибок. Попытка интегрировать полную поддержку античита в ваш форк - это вопрос "Мы можем попробовать, и если это сработает, то будет здорово.. если нам придётся отключить некоторые обнаружения, то процент защиты будет выше, чем у обычного античита форков: 15% и это уже огромный выигрыш.." и во многом зависит от меры возможностей. Потому что причина, по которой мы разделили netc форков (из bdata/netc.dll) на тот, в котором отсутствует большинство античит-функций, может быть понятна любому опытному разработчику: netc-модуль (античит) не рассчитан на все типы настроек, которые разработчик форка может добавить в свою кодовую базу, это было сделано в духе предоставления максимальной свободы и гибкости. Тем более, что многие форки имеют не самых лучших разработчиков, не понимающих, почему им лучше следовать рекомендациям MTA (mtasa-blue) по написанию кода, структуре проекта и максимально приближать свои пользовательские реализации так, как это обычно делает участник MTA, прошедший проверку (ревью) кода. Таким образом, здесь происходит отделение 'чистых' изменений от 'грязного моддинга', который также часто встречается в российских форках, '''использующих один или несколько следующих подходов к кодовой базе своего проекта:
''' 

* Реализация моддинговых GTA: SA проектов внешним 'грязным' способом, как limit adjuster (fastman92 и т.д.)
* Необработанная (raw) загрузка модифицированных данных GTA: SA & .IMG файлов, через распространение предварительно модифицированных установочных папок GTA среди игроков форк клиента. Тем самым полностью игнорируя MTA API для замены моделей и различных игровых процессов.
* Различные грязные патчи, в широком смысле описанные в абзаце выше. Также включает в себя несоблюдение рекомендаций MTA по "Raw memory access" (необработанному доступу к памяти), найденных здесь: https://github.com/multitheftauto/mtasa-blue/wiki/Dev-Tips, что является значительным фактором риска для сценариев, не ожидаемых netc.dll (античитом), так как если он защищает от модификаций памяти, зная их происхождение, и вы просто поместите грязный 'writeProcessMemory' или memcpy в случайный .cpp файл, это вызовет нарушение. Это далеко не всё, и это плохой пример, но просто чтобы вы поняли, почему существуют несовместимости.

=== Получение максимального % античит-защиты ===

Поняв вышесказанное, а также то, что мы стараемся изо всех сил, так как такое использование в качестве "полного античита" для форков никогда не входило в наши планы, и что было бы трудно поддерживать пользовательские модификации каждого, вы можете понять, что мы не можем помочь вам выяснить, что является несовместимым сразу после того, как вы начнёте тестировать netc "с полным античитом" в своём форке. Поэтому вы сами должны либо отключить столько обнаружений, сколько требуется (если вы не можете их исправить - где 'не можете' является показателем отсутствия инженерного опыта), либо, что ещё лучше, разработать исправления, которые позволят вам избежать отключения слишком многих или любых типов обнаружения, тем самым максимизируя потенциальный % античит-функций.

Это означает, что без поддержки команды MTA вам предстоит выяснить, какие настройки/интеграции/несоблюдения MTA API/примеры проблем, описанные ранее в этой статье.. являются виновниками каждого конкретного типа обнаружения, который отправляет вам кики античита после добавления netc "с полным античитом" в ваш форк для тестирования. Мы советуем вам очистить свои интеграции, чтобы избежать необходимости много копаться вручную/выяснять виновника. Для этого обратите внимание на пункты маркированного списка из предыдущего абзаца. Однако, если же прямой виновник найден, приложив все свои усилия, вы должны без каких-либо указаний со стороны MTA придумать альтернативные (более чистые, более соответствующие рекомендациям MTA по написанию кода, API и структуре проекта.. следовательно, менее вероятно несовместимые с полным античитом и тем, что он ожидает) реализации проблемной настройки, найденной в кодовой базе вашего форка. Вы можете видеть, где возможность использовать 'полный античит для форков' становится скорее благосклонностью, чем данностью, особенно с тем состоянием кодовой базы, в котором многие форки, не начав свою разработку по сценарию 'полного античита', выросли, просто написав то, что работает для них, не учитывая такие аспекты. Общая картина того, почему мы не будем поддерживать процесс реинжиниринга, теперь должна быть ясна. Если вы не можете с этим справиться, либо наймите кого-то с большим опытом в компьютерных науках и инженерии, либо отключите больше типов обнаружения античита, и довольствуйтесь всем, что выше 15% обычного netc для форков, лучше что-то, чем ничего. '''Но мы не сможем протянуть руку помощи.''' Любое непонимание этих концепций указывает на отсутствие полноты разработчика (индивидуальных навыков, возможностей для роста) и не может быть отражено на разработчиках MTA.

= '''Давайте перейдём к делу''' =

Если вы считаете, что поняли все концепции, описанные в этой статье, вы можете приступить к внедрению "полного античита для форков":

'''СКАЧАЙТЕ: https://mirror-cdn.multitheftauto.com/bdata/fork-support/netc.dll''' (для использования ''вместо'' "bdata/netc.dll" из стандартного mtasa-blue buildactions/install_data.lua)
Обратите внимание, что версия netc.dll по указанной выше ссылке будет регулярно обновляться, чтобы предоставить форкам все античит-улучшения, поставляемые также и для официальной MTA. Поэтому рекомендуется регулярно получать обновления для вашего форка для обеспечения оптимальной безопасности & надёжности античита

- Замените netc.dll в вашем форк-проекте на вышеуказанный "поддерживаемый для форков" netc с полным античитом.
- Убедитесь, что тип сборки в version.h изменён на UNSTABLE, согласно рекомендациям "массового потребления" для форков в комментариях: [https://github.com/multitheftauto/mtasa-blue/blob/master/Shared/sdk/version.h Shared/sdk/version.h]. В противном случае, вы сведёте на нет все усилия по получению полной античит-защиты.

- Убедитесь, что вы обновили кодовую базу вашего форка до активной основной версии (для которой netc.dll), '''мастер'''-коммита mtasa-blue, по крайней мере до версии "Default", указанной на [https://nightly.mtasa.com/ver/] как "Auto-update default" для последней основной версии, затем сопоставьте указанную ревизию с SHA1-хешем коммита с помощью этого инструмента: https://buildinfo.mtasa.com/index.php - это означает, что не следует использовать начальный выпуск (версию, которая имеет метку выпуска на github), потому что MTA использует модель "MTA как услуга", где игроки получают регулярные обновления, содержащие все основные изменения для оптимального качества и опыта использования новых функций. Последние выпуски netc.dll основаны на этом и могут требовать присутствия мастер-изменений.

- Столкнитесь с некоторыми киками античита в вашем форк-клиенте, этап проб и ошибок начинается здесь. Теперь используйте предыдущие части этого руководства, чтобы либо отключить типы обнаружения античита с помощью disableac в mtaserver.conf, либо, что ещё лучше, потратьте больше сил разработчиков на правильное исправление & очистку ваших пользовательских реализаций, как советовали ранее, чтобы сохранить как можно больше % античит-защиты. Мы советуем не опускаться ниже 85% (как в примере с 'disableac' кодами: 5, 6, 21 было упомянуто, что это относительно 85% и то, что требуется большинству российских тяжёлых модифицированных форков для немедленного запуска и возможности вам подключиться).

Заключительные слова: всегда будет лучше не быть форком в первую очередь. Используйте официальный клиент MTA и просто создайте сервер, со временем со своим пользовательским лаунчером, который будет подключать непосредственно к вашему ряду серверов. Просто внесите все настройки, которые вам нужны (причина для создания форка), взяв за основу "upstream" и создайте PR, Pull request (пул-реквест), используя официальный репозиторий MTA https://github.com/multitheftauto/mtasa-blue, чтобы все выиграли, а вы соблюдали лицензию & не сталкивались с препятствиями, включая античит и приток новых игроков, которые возникают при создании форка. MTA обычно имеет 30000 игроков онлайн одновременно, что также является огромным притоком новых игроков для открытия своего сообщества. Лучше просто не быть форком, но если вам действительно нужно, эта страница является нашим активным взаимодействием с форками для получения лучшего уровня античит-защиты. 
Мы создали этот вариант netc.dll "с полным античитом для форков" в ноябре/декабре 2022 года и опробовали практические результаты и некоторые специфические исправления для лучшей поддержки, с 2 крупнейшими российскими MTA форками, оба из которых готовятся выпустить обновление, включающее это в ближайшие несколько месяцев. Мы также взаимодействовали с разработчиками небольших форков, которые, однако, решили злоупотребить этим (а вместе с этим и нашим доверием), немедленно став токсичными и пытаясь продать netc-модуль "с полным античитом", который мы им дали, что побудило написать и в спешке опубликовать эту вики-статью. Нехорошо, и, пожалуйста, не ведитесь на предложения от упомянутого круга токсичных разработчиков форков, пытающихся продать вам такой netc "с полным античитом", когда вы можете получить более новую версию из официального источника, от нас в этой статье. Работа над этой статьёй в контексте упомянутого инцидента обсуждалась в MTA development discord (приглашение: https://discord.gg/GNN6PRtTnu) в этом посте: https://discord.com/channels/801330706252038164/801330706252038170/1044757943071023155 и аналогично в основном, официальном MTA discord (приглашение: https://discord.gg/mtasa) в этом посте: https://discord.com/channels/278474088903606273/278521065435824128/1044758439357849661

[[EN:Forks_Full_AC]]

RU/Полный античит MTA для форк-проектов

2022-12-13T18:10:42Z

Zver-CR:

__NOTOC__ {{Примечание|Информация на этой странице не относится к официальным сборкам MTA.}}
__NOTOC__ {{Примечание|Это не окончательная версия этой страницы, она будет улучшаться/дополняться/переписываться.}}

Форки MTA, которым недостаточно использовать "обычный netc для форков" (из bdata/netc.dll), как описано на вики-странице [[Forks]], из-за того, что он предлагает очень ограниченную античит-защиту, могут изучить возможности использования нового netc варианта: "полного античита для форков". Это, однако, имеет свои ограничения, относящиеся к особенностям вашего форк-проекта и реализации, которые нелегко объяснить, но эта страница стремится сделать это как можно точнее.

''Эта операция превратит ваш форк в проект с "надлежащим античитом, основанным на методе исправлений", как описано в спойлере в этой теме: https://forum.multitheftauto.com/topic/66858-bounty-for-finding-security-flaws-and-working-cheats-in-mta/, а не максимум 15% 'основанным на сигнатурах' античитом, как описано на вики-странице [[Forks]] для обычных форков.''

Основная идея:
* Модуль netc "с полным античитом для форков" будет предоставлять 95% функций античита, имеющихся в официальных MTA (multitheftauto.com > Кнопка "Download") сборках.
* Чем больше несовместимых функций/реализаций (пользовательских изменений) имеет ваш форк-проект, которые '''вы''' можете отключить (добавив их в белый список обнаружения: '''disableac''' массив в '''mtaserver.conf''', как описано на странице [https://wiki.multitheftauto.com/wiki/RU/Anti-cheat_guide#%3Cdisableac%3E%3C/disableac%3E Anti-cheat guide / Руководство по античиту: DISABLEAC]), тем ниже будет указанное число защиты в процентах.
** '''Например''', если вам нужно отключить 3 различных типа обнаружения (допустим, для российских форков, учитывая загрузку внешних модов вне MTA API/limit adjuster'а, наиболее распространёнными являются: 5, 6, 21), вы получите 85% оставшейся античит-защиты. Хотя это число относительно, так как это даёт разработчикам читов возможность использовать именно эти отключенные категории обнаружения для обеспечения работы их читов/хаков, и эти 3 кода уже предоставляют некоторые конкретные пути для записи в память GTA. 

Понимаете, к чему всё это идёт? Ниже в этой статье появится ссылка на "полный античит для форков", и то, что вы будете делать с ним - это метод проб и ошибок. Попытка интегрировать полную поддержку античита в ваш форк - это вопрос "Мы можем попробовать, и если это сработает, то будет здорово.. если нам придётся отключить некоторые обнаружения, то процент защиты будет выше, чем у обычного античита форков: 15% и это уже огромный выигрыш.." и во многом зависит от меры возможностей. Потому что причина, по которой мы разделили netc форков (из bdata/netc.dll) на тот, в котором отсутствует большинство античит-функций, может быть понятна любому опытному разработчику: netc-модуль (античит) не рассчитан на все типы настроек, которые разработчик форка может добавить в свою кодовую базу, это было сделано в духе предоставления максимальной свободы и гибкости. Тем более, что многие форки имеют не самых лучших разработчиков, не понимающих, почему им лучше следовать рекомендациям MTA (mtasa-blue) по написанию кода, структуре проекта и согласовывать свои пользовательские дополнения с тем, как это обычно делает участник MTA, прошедший проверку (ревью) кода. Таким образом, здесь происходит отделение 'чистых' изменений от 'грязного моддинга', который также часто встречается в российских форках, '''использующих один или несколько следующих подходов к кодовой базе своего проекта:
''' 

* Реализация моддинговых GTA: SA проектов внешним 'грязным' способом, как limit adjuster (fastman92 и т.д.)
* Необработанная (raw) загрузка модифицированных данных GTA: SA & .IMG файлов, через распространение предварительно модифицированных установочных папок GTA среди игроков форк клиента. Тем самым полностью игнорируя MTA API для замены моделей и различных игровых процессов.
* Различные грязные патчи, в широком смысле описанные в абзаце выше. Также включает в себя несоблюдение рекомендаций MTA по "Raw memory access" (необработанному доступу к памяти), найденных здесь: https://github.com/multitheftauto/mtasa-blue/wiki/Dev-Tips, что является значительным фактором риска для сценариев, не ожидаемых netc.dll (античитом), так как если он защищает от модификаций памяти, зная их происхождение, и вы просто поместите грязный 'writeProcessMemory' или memcpy в случайный .cpp файл, это вызовет нарушение. Это далеко не всё, и это плохой пример, но просто чтобы вы поняли, почему существуют несовместимости.

=== Получение максимального % античит-защиты ===

Поняв вышесказанное, а также то, что мы стараемся изо всех сил, так как такое использование в качестве "полного античита" для форков никогда не входило в наши планы, и что было бы трудно поддерживать пользовательские модификации каждого, вы можете понять, что мы не можем помочь вам выяснить, что является несовместимым сразу после того, как вы начнёте тестировать netc "с полным античитом" в своём форке. Поэтому вы сами должны либо отключить столько обнаружений, сколько требуется (если вы не можете их исправить - где 'не можете' является показателем отсутствия инженерного опыта), либо, что ещё лучше, разработать исправления, которые позволят вам избежать отключения слишком многих или любых типов обнаружения, тем самым максимизируя потенциальный % античит-функций.

Это означает, что без поддержки команды MTA вам предстоит выяснить, какие настройки/интеграции/несоблюдения MTA API/примеры проблем, описанные ранее в этой статье.. являются виновниками каждого конкретного типа обнаружения, который отправляет вам кики античита после добавления netc "с полным античитом" в ваш форк для тестирования. Мы советуем вам очистить свои интеграции, чтобы избежать необходимости много копаться вручную/выяснять виновника. Для этого обратите внимание на пункты маркированного списка из предыдущего абзаца. Однако, если же прямой виновник найден, приложив все свои усилия, вы должны без каких-либо указаний со стороны MTA придумать альтернативные (более чистые, более соответствующие рекомендациям MTA по написанию кода, API и структуре проекта.. следовательно, менее вероятно несовместимые с полным античитом и тем, что он ожидает) реализации проблемной настройки, найденной в кодовой базе вашего форка. Вы можете видеть, где возможность использовать 'полный античит для форков' становится скорее благосклонностью, чем данностью, особенно с тем состоянием кодовой базы, в котором многие форки, не начав свою разработку по сценарию 'полного античита', выросли, просто написав то, что работает для них, не учитывая такие аспекты. Общая картина того, почему мы не будем поддерживать процесс реинжиниринга, теперь должна быть ясна. Если вы не можете с этим справиться, либо наймите кого-то с большим опытом в компьютерных науках и инженерии, либо отключите больше типов обнаружения античита, и довольствуйтесь всем, что выше 15% обычного netc для форков, лучше что-то, чем ничего. '''Но мы не сможем протянуть руку помощи.''' Любое непонимание этих концепций указывает на отсутствие полноты разработчика (индивидуальных навыков, возможностей для роста) и не может быть отражено на разработчиках MTA.

= '''Давайте перейдём к делу''' =

Если вы считаете, что поняли все концепции, описанные в этой статье, вы можете приступить к внедрению "полного античита для форков":

'''СКАЧАЙТЕ: https://mirror-cdn.multitheftauto.com/bdata/fork-support/netc.dll''' (для использования ''вместо'' "bdata/netc.dll" из стандартного mtasa-blue buildactions/install_data.lua)
Обратите внимание, что версия netc.dll по указанной выше ссылке будет регулярно обновляться, чтобы предоставить форкам все античит-улучшения, поставляемыми также и для официальной MTA. Поэтому рекомендуется регулярно получать обновления для вашего форка для обеспечения оптимальной безопасности & надёжности античита

- Замените netc.dll в вашем форк-проекте на вышеуказанный "поддерживаемый для форков" netc с полным античитом.
- Убедитесь, что тип сборки в version.h изменён на UNSTABLE, согласно рекомендациям "массового потребления" для форков в комментариях: [https://github.com/multitheftauto/mtasa-blue/blob/master/Shared/sdk/version.h Shared/sdk/version.h]. В противном случае, вы сведёте на нет все усилия по получению полной античит-защиты.

- Убедитесь, что вы обновили кодовую базу вашего форка до активной основной версии (для которой netc.dll), '''мастер'''-коммита mtasa-blue, по крайней мере до версии "Default", указанной на [https://nightly.mtasa.com/ver/] как "Auto-update default" для последней основной версии, затем сопоставьте указанную ревизию с SHA1-хешем коммита с помощью этого инструмента: https://buildinfo.mtasa.com/index.php - это означает, что не следует использовать начальный выпуск (версию, которая имеет метку выпуска на github), потому что MTA использует модель "MTA как услуга", где игроки получают регулярные обновления, содержащие все основные изменения для оптимального качества и опыта использования новых функций. Последние выпуски netc.dll основаны на этом и могут требовать присутствия мастер-изменений.

- Столкнитесь с некоторыми киками античита в вашем форк-клиенте, этап проб и ошибок начинается здесь. Теперь используйте предыдущие части этого руководства, чтобы либо отключить типы обнаружения античита с помощью disableac в mtaserver.conf, либо, что ещё лучше, потратьте больше сил разработчиков на правильное исправление & очистку ваших пользовательских реализаций, как советовали ранее, чтобы сохранить как можно больше % античит-защиты. Мы советуем не опускаться ниже 85% (как в примере с 'disableac' кодами: 5, 6, 21 было упомянуто, что это относительно 85% и то, что требуется большинству российских тяжёлых модифицированных форков для немедленного запуска и возможности вам подключиться).

Заключительные слова: всегда будет лучше не быть форком в первую очередь. Используйте официальный клиент MTA и просто создайте сервер, со временем со своим пользовательским лаунчером, который будет подключать непосредственно к вашему ряду серверов. Просто внесите все настройки, которые вам нужны (причина для создания форка), взяв за основу "upstream" и создайте PR, Pull request (пул-реквест), используя официальный репозиторий MTA https://github.com/multitheftauto/mtasa-blue, чтобы все выиграли, а вы соблюдали лицензию & не сталкивались с препятствиями, включая античит и приток новых игроков, которые возникают при создании форка. MTA обычно имеет 30000 игроков онлайн одновременно, что также является огромным притоком новых игроков для открытия своего сообщества. Лучше просто не быть форком, но если вам действительно нужно, эта страница является нашим активным взаимодействием с форками для получения лучшего уровня античит-защиты. 
Мы создали этот вариант netc.dll "с полным античитом для форков" в ноябре/декабре 2022 года и опробовали практические результаты и некоторые специфические исправления для лучшей поддержки, с 2 крупнейшими российскими MTA форками, оба из которых готовятся выпустить обновление, включающее это в ближайшие несколько месяцев. Мы также взаимодействовали с разработчиками небольших форков, которые, однако, решили злоупотребить этим (а вместе с этим и нашим доверием), немедленно став токсичными и пытаясь продать netc-модуль "с полным античитом", который мы им дали, что побудило написать и в спешке опубликовать эту вики-статью. Нехорошо, и, пожалуйста, не ведитесь на предложения от упомянутого круга токсичных разработчиков форков, пытающихся продать вам такой netc "с полным античитом", когда вы можете получить более новую версию из официального источника, от нас в этой статье. Работа над этой статьёй в контексте упомянутого инцидента обсуждалась в MTA development discord (приглашение: https://discord.gg/GNN6PRtTnu) в этом посте: https://discord.com/channels/801330706252038164/801330706252038170/1044757943071023155 и аналогично в основном, официальном MTA discord (приглашение: https://discord.gg/mtasa) в этом посте: https://discord.com/channels/278474088903606273/278521065435824128/1044758439357849661

[[EN:Forks_Full_AC]]

FileGetPath

2022-05-31T21:20:53Z

Zver-CR: Add OOP syntax

__NOTOC__
{{Server client function}}
{{New feature/item|3.0153|1.5.3|7446|
This function retrieves the path of the given file.
}}

==Syntax==
<syntaxhighlight lang="lua">
string fileGetPath ( file theFile )
</syntaxhighlight>
{{OOP||[[file]]:getPath|path}}

===Required Arguments===
*'''theFile:''' The file you want to get the path.

===Returns===
Returns a ''string'' representing the file path, ''false'' if invalid file was provided.

==Example==
<section name="Server Example 1" class="server" show="true">
<syntaxhighlight lang="lua">
local newFile = fileCreate("test.txt") -- attempt to create a new file
if (newFile) then -- check if the creation succeeded
local path = fileGetPath(newFile)
outputChatBox("New file created at: "..path, root, 0, 255, 0)
fileClose(newFile) -- close the file once you're done with it
end
</syntaxhighlight></section>

==See Also==
{{File functions}}

GetChatboxLayout

2022-04-12T19:15:23Z

Zver-CR: Add 'chat_text_outline'

__NOTOC__
{{Client function}}
Returns information about how the chatbox looks.

These values come from the file called: [[Chatboxpresets.xml]] but it depends on what type of preset you currently have, which is chosen from your settings in the 'Interface' tab.

==Syntax==
<syntaxhighlight lang="lua">bool|int|table getChatboxLayout ( [ string CVar ] )</syntaxhighlight>

===Optional Arguments===
*'''CVar:''' the name of the property you want returned. Can be the following values:
**'''chat_font''' - Returns the chatbox font
**'''chat_lines''' - Returns how many lines the chatbox has
**'''chat_color''' - Returns the background color of the chatbox
**'''chat_text_color''' - Returns the chatbox text color
**'''chat_input_color''' - Returns the background color of the chatbox input
**'''chat_input_prefix_color''' - Returns the color of the input prefix text
**'''chat_input_text_color''' - Returns the color of the text in the chatbox input
**'''chat_scale''' - Returns the scale of the text in the chatbox
**'''chat_position_offset_x''' - Returns the x position offset setting
**'''chat_position_offset_y''' - Returns the y position offset setting
**'''chat_position_horizontal''' - Returns the horizontal alignment setting
**'''chat_position_vertical''' - Returns the vertical alignment setting
**'''chat_text_alignment''' - Returns the text alignment setting
**'''chat_width''' - Returns the scale of the background width
**'''chat_css_style_text''' - Returns whether text fades out over time
**'''chat_css_style_background''' - Returns whether the background fades out over time
**'''chat_line_life''' - Returns how long it takes for text to start fading out
**'''chat_line_fade_out''' - Returns how long takes for text to fade out
**'''chat_use_cegui''' - Returns whether CEGUI is used to render the chatbox
**'''text_scale''' - Returns text scale
**{{Added feature/item|1.6.0|1.5.9|21160|'''chat_text_outline''' - Returns whether text black/white outline is used}}

===Returns===
*4 numbers if the CVar contains "color"
*2 numbers if '''chat_scale''' was entered
*1 number if any other CVar was specified
*a table of all CVar values, if CVar was not specified
*''false'' if an invalid CVar was specified

==Example==
This code makes the chatbox empty when you type /clear
<syntaxhighlight lang="lua" category="client">
addCommandHandler("clear",
function ()
local lines = getChatboxLayout()["chat_lines"]
for i = 1, lines do
outputChatBox("")
end
end
)
</syntaxhighlight>

This code makes the chatbox empty when you type /clear, but with a cleaner code
<syntaxhighlight lang="lua" category="client">
addCommandHandler("clear",
function ()
outputChatbox(('\n'):rep(getChatboxLayout("chat_lines")));
end
)
</syntaxhighlight>

==See Also==
{{GUI_functions}}
{{GUI_events}}

[[en:getChatboxLayout]]
[[ru:getChatboxLayout]]

RU/Places To Chat

2022-01-23T23:29:35Z

Zver-CR:

Есть масса способов пообщаться с другими игроками MTA. Вне зависимости от того, хотите ли вы обсудить ваши игровые тактики, устроить клановые матчи или даже вступить в клан, всегда есть куда пойти.
Конечно, с некоторыми людьми вы можете пообщаться во время игры через внутриигровой чат. Но есть много мест, которые часто посещает значительная часть MTA сообщества. Некоторые из них описаны ниже.

== Форум ==
Первым местом, на которое вы скорее всего наткнётесь, будет официальный форум MTA сообщества. Его можно найти по адресу [https://forum.mtasa.com https://forum.mtasa.com]. Вы можете свободно просматривать и читать, что говорят другие люди, но чтобы изложить свою точку зрения и начать собственные обсуждения, вам понадобится зарегистрироваться на форуме. Это бесплатно и делается посредством нажатия кнопки Sign Up в верхней части страницы.

Форум разделён на ряд категорий и подфорумов. Они упорядочивают все темы, и перед созданием своей собственной темы вам следует убедиться, что вы находитесь в правильном подфоруме. Кроме того, прежде чем писать какие-либо сообщения, удостоверьтесь, что вы прочитали [https://forum.mtasa.com/topic/12275-forum-rules/ правила].

Для русскоязычных пользователей имеется свой собственный [https://forum.mtasa.com/forum/100-russian-русский/ раздел].

== Discord ==
Для получения моментального ответа на что-либо вами сказанное лучше всего подойдёт Discord. По сравнению с IRC, он предлагает встроенную историю чатов, так что даже если вы не в сети, вы всё равно сможете узнать, что произошло в каналах. IRC также предлагает это, но только через IRC Bouncer, за который вам нужно либо заплатить, либо попросить кого-то разместить его для вас.
Он также имеет современный внешний вид и такие возможности, как встраивание ссылок (обычные веб-сайты, а также изображения и видео), удобная подсветка синтаксиса для вставленных фрагментов кода, эмодзи (также пользовательские), реакции на сообщения в чате, [https://store.steampowered.com/about/ Steam] интеграцию и многое другое.
В настоящее время у нас есть некоторые каналы, такие как:
#general - для общения по MTA и оффтопа
#ru-основной - для общения на русском языке
#scripting-help - для вопросов, связанных с Lua скриптами
#help-support - для любых проблем, связанных с MTA:SA клиентом или сервером
#announcements - для всех важных сообщений от нас
...и многие другие.
Ссылка на приглашение [https://discord.com/invite/mtasa здесь]. Всё, что вам нужно, это учётная запись [https://discordapp.com/ Discord]. Вы можете использовать Discord через веб-браузер или загрузить клиент.
Вы можете найти официальное сообщение на форуме [https://forum.mtasa.com/topic/95226-multi-theft-autos-official-discord-server/ здесь].

=== Помощь по скриптингу ===
Существуют Discord каналы для помощи с MTA скриптингом. Вы можете найти их в категории MTA:SA Help на нашем Discord.

==== Как получить помощь ====
* Попробуйте найти ответ на свой вопрос на [[Главная страница|главной странице]], особое внимание на два верхних блока
* Задайте свой вопрос один раз и повторите его только через разумное количество времени, сделав скидку на занятость канала и людей (например, через 10 минут). НЕ через 10 секунд.
* Вопрос, как минимум, должен содержать:
** Что вы пытаетесь сделать.
** Что вы уже смогли сделать.
** Что конкретно не работает, является проблемой. Какие возникают ошибки.
** Возможно, отрывок кода с пояснениями, загруженный на [https://pastebin.mtasa.com pastebin.mtasa.com] или [https://support.discord.com/hc/ru/articles/210298617-Разметка-текста-101-Форматирование-в-чате-Жирный-Курсив-Подчеркнутый- блок кода] для Discord. (''отрывок кода подразумевает относящуюся к делу часть, а НЕ весь скрипт'')

== IRC (Internet Relay Chat) ==
Несмотря на то, что в наши дни IRC используют не так много людей (по сравнению со старыми временами), IRC - сеть чатов, подобная любым другим чат-комнатам, которые можно найти в интернете. Лучший IRC-клиент для Windows - это mIRC, который можно найти [http://www.mirc.com здесь]. Скачайте, установите, настройте, и вы будете готовы. Язык - английский, но существует некоторая вероятность того, что в канале будут и русскоязычные пользователи.
Нужная вам для подключения информация: 
'''Server (сервер) -''' [irc://irc.gtanet.com/mta irc.gtanet.com/mta] 
'''Port (порт) -''' 6667 
Как только вы подключились и получили MOTD (message of the day, "сообщение дня"), чтобы присоединиться к дискуссии MTA, введите /join #mta
Это перенесёт вас в ''канал'' MTA, который в других чат-сетях назывался бы комнатой.
Если вы затрудняетесь, обязательно прочитайте справочные файлы mIRC.
Для получения более детальной помощи по командам сервера, перейдите в окно, которое первым появилось при подключении, и введите /helpop для получения списка категорий помощи.

== Другое ==
Это не все места/способы общения с другими членами MTA сообщества. Имеется много форумов, отличных от официального MTA, например, [http://www.gtaforums.com GTAForums], являющийся наиболее популярным неофициальным форумом GTA сообщества. Хоть там обсуждают и не только MTA, но игра по сети является довольно популярной темой общения.

Пожалуйста, не стесняйтесь редактировать эту страницу, если вам есть, что добавить.

[[en:Places To Chat]]
[[uk:Places To Chat]]
[[es:Places_To_Chat_ES]]
[[hu:Places To Chat]]

[[Category:Поддержка]]

Undocumented Items

2021-09-23T04:34:59Z

Zver-CR: Remove documented pages

This page lists all MTA SA functions and events which don't have the necessary documentation for scripters to allow them to use the functions or events. Documenting these will require looking through the source code, which is available in the [https://github.com/multitheftauto/mtasa-blue MTA SA GitHub repository], to get the necessary parameters.
__NOTOC__
== Client functions that need documenting ==
(None)

== Server functions that need documenting ==
(None)

== Client events that need documenting ==
(None)

== Server events that need documenting ==
(None)

== Other undocumented pages ==
(None)

Template:Client player functions

2021-09-11T16:24:17Z

Zver-CR: Add getPlayerMapOpacity

* [[forcePlayerMap]]
* [[getLocalPlayer]]
* [[getPlayerBlurLevel]]
* [[getPlayerFromName]]
* [[getPlayerMapBoundingBox]]
{{New items|3.0159|1.5.8|
* [[getPlayerMapOpacity]]
|20945}}
* [[getPlayerMoney]]
* [[getPlayerName]]
* [[getPlayerNametagColor]]
* [[getPlayerNametagText]]
* [[getPlayerPing]]

* [[getPlayerTeam]]
* [[getPlayerWantedLevel]]
* [[givePlayerMoney]]
* [[isPlayerHudComponentVisible]]
* [[isPlayerMapForced]]
* [[isPlayerMapVisible]]
* [[isPlayerNametagShowing]]
* [[isVoiceEnabled]]
{{New items|3.0158|1.5.7|
* [[resetBlurLevel]]
|20450}}
* [[setPlayerBlurLevel]]
* [[setPlayerHudComponentVisible]]
* [[setPlayerMoney]]
* [[setPlayerNametagColor]]
* [[setPlayerNametagShowing]]
* [[setPlayerNametagText]]
* [[takePlayerMoney]]

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

GetPlayerMapOpacity

2021-09-11T16:23:54Z

Zver-CR: Created page with "__NOTOC__ {{Client function}} {{New feature/item|3.0159|1.5.8|20945|This function allows to get the opacity of the radar map (F11).}} ==Syntax== <syntaxhighlight lang="lua">..."

__NOTOC__
{{Client function}}
{{New feature/item|3.0159|1.5.8|20945|This function allows to get the opacity of the radar map (F11).}}

==Syntax==
<syntaxhighlight lang="lua">
int getPlayerMapOpacity ( )
</syntaxhighlight>
{{OOP||[[Player]].getMapOpacity}}

===Returns===
Returns an [[integer]] value from 0 to 255, where 0 is fully transparent and 255 is fully opaque.

==Example==
{{Example}}

==Requirements==
{{Requirements|n/a|1.5.8-9.20945}}

==See Also==
{{Client_player_functions}}

Undocumented Items

2021-08-18T10:21:30Z

Zver-CR:

This page lists all MTA SA functions and events which don't have the necessary documentation for scripters to allow them to use the functions or events. Documenting these will require looking through the source code, which is available in the [https://github.com/multitheftauto/mtasa-blue MTA SA GitHub repository], to get the necessary parameters.
__NOTOC__
== Client functions that need documenting ==
*[[engineStreamingFreeUpMemory]]
*[[engineStreamingGetUsedMemory]]
*[[isChatInputBlocked]]
*[[isShowCollisionsEnabled]]
*[[showSound]]
*[[isShowSoundEnabled]]

== Server functions that need documenting ==
(None)

== Client events that need documenting ==
(None)

== Server events that need documenting ==
(None)

== Other undocumented pages ==
(None)

Template:Client output functions

2021-08-18T10:18:53Z

Zver-CR: Add clearDebugBox

{{New items|3.0156|1.5.5|
* [[clearChatBox]]
|14165}}
{{New items|3.0159|1.5.8|
* [[clearDebugBox]]
|20854}}
* [[isChatVisible]]
* [[outputChatBox]]
* [[outputConsole]]
* [[outputDebugString]]
* [[showChat]]

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

ClearDebugBox

2021-08-18T10:18:23Z

Zver-CR: Created page with "__NOTOC__ {{Client function}} {{New feature/item|3.0159|1.5.8|20854|This function clears the debug box.}} ==Syntax== <syntaxhighlight lang="lua"> bool clearDebugBox ( ) </syn..."

__NOTOC__
{{Client function}}
{{New feature/item|3.0159|1.5.8|20854|This function clears the debug box.}}

==Syntax==
<syntaxhighlight lang="lua">
bool clearDebugBox ( )
</syntaxhighlight>

===Returns===
Always returns ''true''.

==Example==
This example clears the debug window when any new debug message is displayed.
<syntaxhighlight lang="lua">
addEventHandler ( "onClientDebugMessage", root,
function ( )
clearDebugBox ( )
end
)
</syntaxhighlight>

==Requirements==
{{Requirements|n/a|1.5.8-9.20854|}}

==See Also==
{{Client_output_functions}}

Undocumented Items

2021-08-12T18:42:59Z

Zver-CR: New functions

This page lists all MTA SA functions and events which don't have the necessary documentation for scripters to allow them to use the functions or events. Documenting these will require looking through the source code, which is available in the [https://github.com/multitheftauto/mtasa-blue MTA SA GitHub repository], to get the necessary parameters.
__NOTOC__
== Client functions that need documenting ==
*[[engineStreamingFreeUpMemory]]
*[[engineStreamingGetUsedMemory]]
*[[clearDebugBox]]
*[[isShowCollisionsEnabled]]
*[[showSound]]
*[[isShowSoundEnabled]]

== Server functions that need documenting ==
(None)

== Client events that need documenting ==
(None)

== Server events that need documenting ==
(None)

== Other undocumented pages ==
(None)

DxGetStatus

2021-08-06T14:22:21Z

Zver-CR:

{{Client function}}
__NOTOC__
This function gets information about various internal datum

==Syntax==
<syntaxhighlight lang="lua">
table dxGetStatus ( )
</syntaxhighlight>

===Returns===
Returns a table with the following entries:
*'''TestMode:''' The current dx test mode. See [[dxSetTestMode]].
*'''VideoCardName:''' The name of the graphics card.
*'''VideoCardRAM:''' The installed memory in MB of the graphics card.
*'''VideoCardPSVersion:''' The maximum pixel shader version of the graphics card.
*'''VideoCardMaxAnisotropy:''' The maximum anisotropic filtering available. (0-4 which respectively mean: off,2x,4x,8x,16x)
*'''VideoCardNumRenderTargets:''' The maximum number of simultaneous render targets a shader can use.
*'''VideoMemoryFreeForMTA:''' The amount of memory in MB available for MTA to use. '''When this gets to zero, [[guiCreateFont]], [[dxCreateFont]] and [[dxCreateRenderTarget]] will fail.'''
*'''VideoMemoryUsedByFonts:''' The amount of graphic memory in MB used by custom fonts.
*'''VideoMemoryUsedByTextures:''' The amount of graphic memory in MB used by textures.
*'''VideoMemoryUsedByRenderTargets:''' The amount of graphic memory in MB used by render targets.
*'''SettingWindowed:''' The windowed setting. (true/false)
*'''SettingFullScreenStyle:''' Display style when in full screen mode. (0-2 which respectively mean: Standard, Borderless window, Borderless keep res)
*'''SettingFXQuality:''' The FX Quality. (0-3)
*'''SettingDrawDistance:''' The draw distance setting. (0-100)
*'''SettingVolumetricShadows:''' The volumetric shadows setting. (true/false)
*'''SettingStreamingVideoMemoryForGTA:''' The usable graphics memory setting. (64-256)
*'''SettingAnisotropicFiltering:''' The anisotropic filtering setting. (0-4 which respectively mean: off,2x,4x,8x,16x)
*'''SettingAntiAliasing:''' The anti-aliasing setting. (0-3 which respectively mean: off,1x,2x,3x)
*'''SettingHeatHaze:''' The heat haze setting. (true/false)
*'''SettingGrassEffect:''' The grass effect setting. (true/false)
*'''Setting32BitColor:''' The color depth of the screen. (false is 16bit, true is 32bit)
*'''SettingHUDMatchAspectRatio:''' The hud match aspect ratio setting. (true/false)
*'''SettingAspectRatio:''' The aspect ratio setting. ("auto", "4:3", "16:10", "16:9")
*'''SettingFOV:''' The FOV setting.
*'''SettingHighDetailVehicles:''' High detail vehicles setting. (true/false)
{{New feature/item|3.0159|1.5.8|20508|
*'''SettingHighDetailPeds:''' High detail peds setting. (true/false)
}}
*'''AllowScreenUpload:''' The allows screen uploads setting. (true/false)
*'''DepthBufferFormat:''' The format of the shader readable depth buffer, or 'unknown' if not available.
{{New feature/item|3.0159|1.5.8|20901|
*'''TotalPhysicalMemory:''' The amount of total physical memory in MB.
}}
*'''UsingDepthBuffer:''' ''true'' if the depth buffer is used, ''false'' otherwise.
==Example==
<syntaxhighlight lang="lua">
addCommandHandler( "getinfo",
function( )
local info = dxGetStatus( )
for k, v in pairs( info ) do
outputChatBox( k .. " : " .. tostring( v ) )
end
end
)
</syntaxhighlight>

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.3.0-9.04715|Added DepthBufferFormat argument}}
{{ChangelogItem|1.3.0-9.04811|Added VideoCardMaxAnisotropy, SettingAnisotropicFiltering, SettingAntiAliasing, SettingHeatHaze, SettingGrassEffect and Setting32BitColor arguments}}
{{ChangelogItem|1.3.4-9.05731|Added SettingHUDMatchAspectRatio and SettingAspectRatio}}
{{ChangelogItem|1.4.1-9.07181|Added SettingFOV}}
{{ChangelogItem|1.4.1-9.07310|Added VideoCardNumRenderTargets}}
{{ChangelogItem|1.5.2-9.07816|Added UsingDepthBuffer}}
{{ChangelogItem|1.5.3-9.11199|Added SettingHighDetailVehicles}}
{{ChangelogItem|1.5.5-9.11814|Added SettingFullScreenStyle Fixed SettingWindowed}}
{{ChangelogItem|1.5.8-9.20508|Added SettingHighDetailPeds}}
{{ChangelogItem|1.5.8-9.20901|Added TotalPhysicalMemory}}

==See Also==
{{Drawing_functions}}

[[hu:dxGetStatus]]

DxGetStatus

2021-08-06T14:20:41Z

Zver-CR: Add 'TotalPhysicalMemory'

{{Client function}}
__NOTOC__
This function gets information about various internal datum

==Syntax==
<syntaxhighlight lang="lua">
table dxGetStatus ( )
</syntaxhighlight>

===Returns===
Returns a table with the following entries:
*'''TestMode:''' The current dx test mode. See [[dxSetTestMode]].
*'''VideoCardName:''' The name of the graphics card.
*'''VideoCardRAM:''' The installed memory in MB of the graphics card.
*'''VideoCardPSVersion:''' The maximum pixel shader version of the graphics card.
*'''VideoCardMaxAnisotropy:''' The maximum anisotropic filtering available. (0-4 which respectively mean: off,2x,4x,8x,16x)
*'''VideoCardNumRenderTargets:''' The maximum number of simultaneous render targets a shader can use.
*'''VideoMemoryFreeForMTA:''' The amount of memory in MB available for MTA to use. '''When this gets to zero, [[guiCreateFont]], [[dxCreateFont]] and [[dxCreateRenderTarget]] will fail.'''
*'''VideoMemoryUsedByFonts:''' The amount of graphic memory in MB used by custom fonts.
*'''VideoMemoryUsedByTextures:''' The amount of graphic memory in MB used by textures.
*'''VideoMemoryUsedByRenderTargets:''' The amount of graphic memory in MB used by render targets.
*'''SettingWindowed:''' The windowed setting. (true/false)
*'''SettingFullScreenStyle:''' Display style when in full screen mode. (0-2 which respectively mean: Standard, Borderless window, Borderless keep res)
*'''SettingFXQuality:''' The FX Quality. (0-3)
*'''SettingDrawDistance:''' The draw distance setting. (0-100)
*'''SettingVolumetricShadows:''' The volumetric shadows setting. (true/false)
*'''SettingStreamingVideoMemoryForGTA:''' The usable graphics memory setting. (64-256)
*'''SettingAnisotropicFiltering:''' The anisotropic filtering setting. (0-4 which respectively mean: off,2x,4x,8x,16x)
*'''SettingAntiAliasing:''' The anti-aliasing setting. (0-3 which respectively mean: off,1x,2x,3x)
*'''SettingHeatHaze:''' The heat haze setting. (true/false)
*'''SettingGrassEffect:''' The grass effect setting. (true/false)
*'''Setting32BitColor:''' The color depth of the screen. (false is 16bit, true is 32bit)
*'''SettingHUDMatchAspectRatio:''' The hud match aspect ratio setting. (true/false)
*'''SettingAspectRatio:''' The aspect ratio setting. ("auto", "4:3", "16:10", "16:9")
*'''SettingFOV:''' The FOV setting.
*'''SettingHighDetailVehicles:''' High detail vehicles setting (true/false).
{{New feature/item|3.0159|1.5.8|20508|
*'''SettingHighDetailPeds:''' High detail peds setting (true/false).
}}
*'''AllowScreenUpload:''' The allows screen uploads setting. (true/false)
*'''DepthBufferFormat:''' The format of the shader readable depth buffer, or 'unknown' if not available.
{{New feature/item|3.0159|1.5.8|20901|
*'''TotalPhysicalMemory:''' The amount of total physical memory in MB.
}}
*'''UsingDepthBuffer:''' ''true'' if the depth buffer is used, ''false'' otherwise.
==Example==
<syntaxhighlight lang="lua">
addCommandHandler( "getinfo",
function( )
local info = dxGetStatus( )
for k, v in pairs( info ) do
outputChatBox( k .. " : " .. tostring( v ) )
end
end
)
</syntaxhighlight>

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.3.0-9.04715|Added DepthBufferFormat argument}}
{{ChangelogItem|1.3.0-9.04811|Added VideoCardMaxAnisotropy, SettingAnisotropicFiltering, SettingAntiAliasing, SettingHeatHaze, SettingGrassEffect and Setting32BitColor arguments}}
{{ChangelogItem|1.3.4-9.05731|Added SettingHUDMatchAspectRatio and SettingAspectRatio}}
{{ChangelogItem|1.4.1-9.07181|Added SettingFOV}}
{{ChangelogItem|1.4.1-9.07310|Added VideoCardNumRenderTargets}}
{{ChangelogItem|1.5.2-9.07816|Added UsingDepthBuffer}}
{{ChangelogItem|1.5.3-9.11199|Added SettingHighDetailVehicles}}
{{ChangelogItem|1.5.5-9.11814|Added SettingFullScreenStyle Fixed SettingWindowed}}
{{ChangelogItem|1.5.8-9.20508|Added SettingHighDetailPeds}}
{{ChangelogItem|1.5.8-9.20901|Added TotalPhysicalMemory}}

==See Also==
{{Drawing_functions}}

[[hu:dxGetStatus]]

CJ Clothes\Shoes (3)

2021-04-29T15:44:19Z

Zver-CR: typo

{| border="1"
| {{Clothes|index=0|type=3|model=feet|texture=foot}}
| {{Clothes|index=1|type=3|model=biker|texture=cowboyboot2}}
| {{Clothes|index=2|type=3|model=bask1|texture=bask2semi}}
| {{Clothes|index=3|type=3|model=bask1|texture=bask1eris}}
| {{Clothes|index=4|type=3|model=sneaker|texture=sneakerbincgang}}
| {{Clothes|index=5|type=3|model=sneaker|texture=sneakerbincblu}}
|-
| {{Clothes|index=6|type=3|model=sneaker|texture=sneakerbincblk}}
| {{Clothes|index=7|type=3|model=flipflop|texture=sandal}}
| {{Clothes|index=8|type=3|model=flipflop|texture=sandalsock}}
| {{Clothes|index=9|type=3|model=flipflop|texture=flipflop}}
| {{Clothes|index=10|type=3|model=bask1|texture=hitop}}
| {{Clothes|index=11|type=3|model=conv|texture=convproblk}}
|-
| {{Clothes|index=12|type=3|model=conv|texture=convproblu}}
| {{Clothes|index=13|type=3|model=conv|texture=convprogrn}}
| {{Clothes|index=14|type=3|model=sneaker|texture=sneakerprored}}
| {{Clothes|index=15|type=3|model=sneaker|texture=sneakerproblu}}
| {{Clothes|index=16|type=3|model=sneaker|texture=sneakerprowht}}
| {{Clothes|index=17|type=3|model=bask1|texture=bask1prowht}}
|-
| {{Clothes|index=18|type=3|model=bask1|texture=bask1problk}}
| {{Clothes|index=19|type=3|model=biker|texture=boxingshoe}}
| {{Clothes|index=20|type=3|model=conv|texture=convheatblk}}
| {{Clothes|index=21|type=3|model=conv|texture=convheatred}}
| {{Clothes|index=22|type=3|model=conv|texture=convheatorn}}
| {{Clothes|index=23|type=3|model=sneaker|texture=sneakerheatwht}}
|-
| {{Clothes|index=24|type=3|model=sneaker|texture=sneakerheatgry}}
| {{Clothes|index=25|type=3|model=sneaker|texture=sneakerheatblk}}
| {{Clothes|index=26|type=3|model=bask1|texture=bask2heatwht}}
| {{Clothes|index=27|type=3|model=bask1|texture=bask2heatband}}
| {{Clothes|index=28|type=3|model=bask1|texture=timbergrey}}
| {{Clothes|index=29|type=3|model=bask1|texture=timberred}}
|-
| {{Clothes|index=30|type=3|model=bask1|texture=timberfawn}}
| {{Clothes|index=31|type=3|model=bask1|texture=timberhike}}
| {{Clothes|index=32|type=3|model=biker|texture=cowboyboot}}
| {{Clothes|index=33|type=3|model=biker|texture=biker}}
| {{Clothes|index=34|type=3|model=biker|texture=snakeskin}}
| {{Clothes|index=35|type=3|model=shoe|texture=shoedressblk}}
|-
| {{Clothes|index=36|type=3|model=shoe|texture=shoedressbrn}}
| {{Clothes|index=37|type=3|model=shoe|texture=shoespatz}}
|}

[[pl:CJ_Clothes%5CShoes_(3)]]

Shader examples

2021-03-25T18:51:19Z

Zver-CR: http > https

This page contains some example shader resources to try. If you are looking to make your own, please be sure to read about the [[Shader|shader element]] as well.
 
__TOC__
==Road shine==
[[Image:RoadShineScreen.jpg|200px|thumb|left|Road shine]]
<table border=0><tr><td valign=top height=170>
[https://nightly.mtasa.com/files/shaders/shader_roadshine.zip Download shader_roadshine.zip]   ''Requires Shader Model 2 graphics card''
 
This resource creates a light reflection effect on the ground (looks best when moving).
It uses a custom flag in the effect file to generate [https://en.wikipedia.org/wiki/Surface_normal surface normals] for the ground model:
<syntaxhighlight lang="lua">
int CUSTOMFLAGS
<
string createNormals = "yes";
>;</syntaxhighlight>
Surface normals are not usually present in the ground and building models, but are useful for creating lighting effects such as these.
</td></tr></table>

==Road shine 2==
[[Image:RoadShine2Screen.jpg|200px|thumb|left|Road shine 2]]
<table border=0><tr><td valign=top height=170>
[https://nightly.mtasa.com/files/shaders/shader_roadshine2.zip Download shader_roadshine2.zip]   ''Requires Shader Model 2 graphics card''
 
Bit more complicated than the first Road shine, as it tracks the sun or moon to calculate the position of the highlight.
The effect can be hard to see depending on the time of day.
 
Best used with the play resource as the model it modifies is near the initial spawn point.
</td></tr></table>

==Road shine 3 (Deluxe edition)==
[[Image:RoadShine3Screen.jpg|200px|thumb|left|Road shine 3]]
<table border=0><tr><td valign=top height=170>
[https://nightly.mtasa.com/files/shaders/shader_roadshine3.zip Download shader_roadshine3.zip]   ''Requires Shader Model 2 graphics card''
 
This resource shows how to:
* Stop a wild card match shader from being applied to certain world textures.
* Use isLineOfSightClear to stop an effect when something is not visible (The sun in this case).
* Use a shader maxDrawDistance setting to avoid GPU overload.

The final effect is a faster shader with less rendering issues than the previous two road shine examples.
 
</td></tr></table>

==UV scroll==
[[Image:UVScollScreen.jpg|200px|thumb|left|UV scroll]]
<table border=0><tr><td valign=top height=170>
[https://nightly.mtasa.com/files/shaders/shader_uv_scroll.zip Download shader_uv_scroll.zip]
 
This resource scrolls a texture from left to right. It doesn't use vertex or pixels shaders, so it should work on all hardware.
</td></tr></table>

==UV scripted==
[[Image:UVScriptedScreen.jpg|200px|thumb|left|UV scripted]]
<table border=0><tr><td valign=top height=170>
[https://nightly.mtasa.com/files/shaders/shader_uv_scripted.zip Download shader_uv_scripted.zip]
 
This resource controls a texture's UVs using Lua. It shows that anything is possible if you can imagine it.
</td></tr></table>

==Car paint==
[[Image:CarPaintScreen.jpg|200px|thumb|left|Car paint]]
<table border=0><tr><td valign=top height=170>
[https://nightly.mtasa.com/files/shaders/shader_car_paint.zip Download shader_car_paint.zip]   ''Requires Shader Model 2 graphics card''
 
This resource shows you how to apply a shader to the vehicle models. The shader itself is not that great, so don't get your hopes up.
</td></tr></table>

==Water==
[[Image:WaterScreen.jpg|200px|thumb|left|Water]]
<table border=0><tr><td valign=top height=170>
[https://nightly.mtasa.com/files/shaders/shader_water.zip Download shader_water.zip]   ''Requires Shader Model 2 graphics card''
 
This resource applies a shader to the GTA world water. The Lua script shows how to use a timer to transfer the conventional water color setting to the shader.
</td></tr></table>

==Bloom==
[[Image:BloomScreen.jpg|200px|thumb|left|Bloom]]
<table border=0><tr><td valign=top height=170>
[https://nightly.mtasa.com/files/shaders/shader_bloom.zip Download shader_bloom.zip]   ''Requires Shader Model 2 graphics card''
 
This resource shows you how 'bounce' full screen effects using a render target pool. It uses the ''onClientHUDRender'' event to exclude the HUD from the effect.
</td></tr></table>

==Block world==
[[Image:BlockWorld.jpg|200px|thumb|left|Block world]]
<table border=0><tr><td valign=top height=170>
[https://nightly.mtasa.com/files/shaders/shader_block_world.zip Download shader_block_world.zip]   ''Requires Shader Model 2 graphics card''
 
This resource makes the textures look all blocky. It also changes colors when the 'k' key is pressed.
</td></tr></table>

==Texture names==
[[Image:TexNames.jpg|200px|thumb|left|Texture names]]
<table border=0><tr><td valign=top height=170>
[https://nightly.mtasa.com/files/shaders/shader_tex_names.zip Download shader_tex_names.zip]
 
This resource is only a tool, and doesn't do anything pretty. It shows a list of the current visible texture names, and highlights the selected texture. Ideal for finding a texture name to use with [[engineApplyShaderToWorldTexture]].

num_8 shows/hides the texture list, num_7 and num_9 step through the list, and 'k' copies the current texture name to the clipboard.
</td></tr></table>

==Skid marks==
[[Image:SkidMarks.jpg|200px|thumb|left|Skid marks]]
<table border=0><tr><td valign=top height=170>
[https://nightly.mtasa.com/files/shaders/shader_skidmarks.zip Download shader_skidmarks.zip]   ''Requires Shader Model 2 graphics card''
 
This resource shows you how to do multiple passes in a shader, and input different variables to the vertex shader for each pass.
Use the command '''/skidmarks 1-4''' to see the different effects. (You have skid a car to see it!)
 
</td></tr></table>

==HDR contrast==
[[Image:ShaderContrast.jpg|200px|thumb|left|HDR contrast]]
<table border=0><tr><td valign=top height=170>
[https://nightly.mtasa.com/files/shaders/shader_contrast.zip Download shader_contrast.zip]   ''Requires Shader Model 2 graphics card''
 
This resource applies a 'High Dynamic Range' contrast effect. It uses a 1 pixel render target to sample the whole scene, and then uses that to brighten or darken the next frame.
So going into somewhere dark will automatically brighten the scene, and visa versa
 
</td></tr></table>

==Tessellation==
[[Image:shader_flag.jpg|200px|thumb|left|Tessellation action]]
<table border=0><tr><td valign=top height=170>
[https://nightly.mtasa.com/files/shaders/shader_flag.zip Download shader_flag.zip]   ''Requires Shader Model 2 graphics card''
 
This resource shows how to use shader tessellation to animate the shape of a dxDrawImage and use shader transform to give it a 3rd dimension.

The example has a GUI (press numpad-8) so you can fiddle with the settings.
 
</td></tr></table>

==Radial blur==
[[Image:shader_radial_blur.jpg|200px|thumb|left|Radial blur]]
<table border=0><tr><td valign=top height=170>
[https://nightly.mtasa.com/files/shaders/shader_radial_blur.zip Download shader_radial_blur.zip]   ''Requires Shader Model 2 graphics card''
 
This resource sort of looks a little bit like the GTAIV motion blur you get when you move the mouse quickly, or drive a fast car. The fast car effect is a bit more subtle than the screen shot would suggest, as it leaves the center of the screen nice and clear so you can see where you are going.

It also has the option of suspending the effect during times of low FPS. Check the two settings at the top of '''''c_radial_blur.lua'''''.
 
The file '''''c_switch.lua''''' contains information on how to toggle the effect from another resource using events.
 
</td></tr></table>

==Detail==
[[Image:shader_detail.jpg|200px|thumb|left|Detail]]
<table border=0><tr><td valign=top height=170>
[https://nightly.mtasa.com/files/shaders/shader_detail.zip Download shader_detail.zip]   ''Requires Shader Model 2 graphics card''
 
Applies a few monochrome detail textures, at various scales, to (parts of) the world.

(Not finished and probably never will be.)

</td></tr></table>

==Ped morph==
[[Image:PedMorphScreen.jpg|200px|thumb|left|Ped morph]]
<table border=0><tr><td valign=top height=170>
[https://nightly.mtasa.com/files/shaders/shader_ped_morph.zip Download shader_ped_morph.zip]   ''Requires Shader Model 2 graphics card''
 
This resource uses a vertex shader to modify the geometry of a ped model as it is rendered.
 
When the resource has started, use the 'k' and 'l' keys to change morph size.

</td></tr></table>

==Ped shell==
[[Image:PedShellScreen.jpg|200px|thumb|left|Ped shell]]
<table border=0><tr><td valign=top height=170>
[https://nightly.mtasa.com/files/shaders/shader_ped_shell.zip Download shader_ped_shell.zip]   ''Requires Shader Model 2 graphics card''
 
This resource draws a translucent effect as a shader layer. The first pass is done by GTA, and the vertex shader is only applied in the second to add the effect 'on top' of the standard output.
 
When the resource has started, use the 'm' key to see the shell effect.

</td></tr></table>

==Hud mask==
[[Image:Shader_hud_mask.jpg|200px|thumb|left|Hud mask]]
<table border=0><tr><td valign=top height=170>
[https://nightly.mtasa.com/files/shaders/shader_hud_mask.zip Download shader_hud_mask.zip]
 
This resource shows how to draw a hud texture with a shape mask.
</td></tr></table>

==dxDrawCircle==
[[Image:dxDrawCircle.jpg|200px|thumb|left|dxDrawCircle]]
<table border=0><tr><td valign=top height=170>
[https://nightly.mtasa.com/files/shaders/shader_circle.zip Download shader_circle.zip]
 
This resource exports a 'dxDrawCircle' function for use in your own scripts.
 
Example resource calling dxDrawCircle function from shader_circle: [https://nightly.mtasa.com/files/shaders/circle_example.zip circle_example.zip]
</td></tr></table>

GetRoofPosition

2021-01-03T21:52:00Z

Zver-CR:

__NOTOC__
{{Client function}}
{{New feature/item|3.0160|1.5.8|20675|
This function gets the Z level of the lowest roof above a point.
It is required that the point is near enough to the local player so that it's within the area where collision data is loaded.}}

==Syntax==
<syntaxhighlight lang="lua">
float getRoofPosition ( float x, float y, float z )
</syntaxhighlight>

===Required Arguments===
*'''x''': A [[float]]ing point number representing the X world coordinate of the point.
*'''y''': A [[float]]ing point number representing the Y world coordinate of the point.
*'''z''': A [[float]]ing point number representing the Z world coordinate of the point.

===Returns===
Returns a [[float]] with the lowest roof-level Z coord if parameters are valid, ''false'' if the point you tried to test is outside the loaded world map.

==Example==
This example starts to shake the player's camera if there is no roof over him.
<syntaxhighlight lang="lua">
setTimer (
function ( )
local playerX, playerY, playerZ = getElementPosition ( localPlayer )
local roofZ = getRoofPosition ( playerX, playerY, playerZ )
setCameraShakeLevel ( ( roofZ ) and 0 or 255 )
end, 100, 0
)
</syntaxhighlight>

==Requirements==
{{Requirements|n/a|1.5.8-9.20675|}}

==See Also==
{{Client_world_functions}}

GetRoofPosition

2021-01-03T21:37:17Z

Zver-CR: Created page with "__NOTOC__ {{Client function}} {{New feature/item|3.0160|1.5.8|20675| This function gets the Z level of the lowest roof above a point. It is required that the point is near eno..."

__NOTOC__
{{Client function}}
{{New feature/item|3.0160|1.5.8|20675|
This function gets the Z level of the lowest roof above a point.
It is required that the point is near enough to the local player so that it's within the area where collision data is loaded.}}

==Syntax==
<syntaxhighlight lang="lua">
float getRoofPosition ( float x, float y, float z )
</syntaxhighlight>

===Required Arguments===
*'''x''': A [[float]]ing point number representing the X world coordinate of the point.
*'''y''': A [[float]]ing point number representing the Y world coordinate of the point.
*'''z''': A [[float]]ing point number representing the Z world coordinate of the point.

===Returns===
Returns a [[float]] with the lowest roof-level Z coord if parameters are valid, ''false'' if the point you tried to test is outside the loaded world map.

==Example==
This example starts to shake the player's camera if there is no roof over it.
<syntaxhighlight lang="lua">
setTimer (
function ( )
local playerX, playerY, playerZ = getElementPosition ( localPlayer )
local roofZ = getRoofPosition ( playerX, playerY, playerZ )
setCameraShakeLevel ( ( roofZ ) and 0 or 255 )
end, 100, 0
)
</syntaxhighlight>

==Requirements==
{{Requirements|n/a|1.5.8-9.20675|}}

==See Also==
{{Client_world_functions}}

Template:Client world functions

2021-01-03T21:25:33Z

Zver-CR: Add getRoofPosition

* [[areTrafficLightsLocked]]
* [[createSWATRope]]
* [[getAircraftMaxHeight]]
* [[getAircraftMaxVelocity]]
* [[getBirdsEnabled]]
* [[getCloudsEnabled]]
* [[getFarClipDistance]]
* [[getFogDistance]]
* [[getGameSpeed]]
* [[getGarageBoundingBox]]
* [[getGaragePosition]]
* [[getGarageSize]]
* [[getGravity]]
* [[getGroundPosition]]
* [[getHeatHaze]]
* [[getInteriorFurnitureEnabled]]
* [[getInteriorSoundsEnabled]]
* [[getJetpackMaxHeight]]
* [[getMinuteDuration]]
* [[getMoonSize]]
* [[getNearClipDistance]]
* [[resetNearClipDistance]]
* [[getOcclusionsEnabled]]
{{New items|3.0156|1.5.5|
*[[getPedsLODDistance]]
*[[setPedsLODDistance]]
*[[resetPedsLODDistance]]
|13771}}
* [[getPlayerBlurLevel]]
* [[getRainLevel]]
{{New items|3.0160|1.5.8|
*[[getRoofPosition]]
|20675}}
* [[getScreenFromWorldPosition]]
* [[getSunColor]]
* [[getSunSize]]
* [[getTime]]
* [[getTrafficLightState]]
* [[getVehiclesLODDistance]]
* [[getWeather]]
* [[getWindVelocity]]
* [[getWorldFromScreenPosition]]
* [[getZoneName]]
* [[isAmbientSoundEnabled]]
* [[isGarageOpen]]
* [[isLineOfSightClear]]
* [[isWorldSoundEnabled]]
* [[isWorldSpecialPropertyEnabled]]
* [[processLineOfSight]]
* [[removeWorldModel]]
* [[resetAmbientSounds]]
{{New items|3.0158|1.5.7|
*[[resetBlurLevel]]
|20450}}
* [[resetFarClipDistance]]
* [[resetFogDistance]]
* [[resetHeatHaze]]
* [[resetMoonSize]]
* [[resetRainLevel]]
* [[resetSkyGradient]]
* [[resetSunColor]]
* [[resetSunSize]]
* [[resetVehiclesLODDistance]]
* [[resetWindVelocity]]
* [[resetWorldSounds]]
{{New items|3.0160|1.5.8|
*[[resetColorFilter]]
|20718}}
* [[restoreAllWorldModels]]
* [[restoreWorldModel]]
* [[setAircraftMaxHeight]]
* [[setAircraftMaxVelocity]]
* [[setAmbientSoundEnabled]]
* [[setBirdsEnabled]]
* [[setCloudsEnabled]]
* [[setFarClipDistance]]
* [[setFogDistance]]
* [[setGameSpeed]]
* [[setGarageOpen]]
* [[setGravity]]
* [[setHeatHaze]]
* [[setInteriorFurnitureEnabled]]
* [[setInteriorSoundsEnabled]]
* [[setJetpackMaxHeight]]
* [[setMinuteDuration]]
* [[setMoonSize]]
* [[setNearClipDistance]]
* [[setOcclusionsEnabled]]
* [[setPlayerBlurLevel]]
* [[setRainLevel]]
* [[setSkyGradient]]
* [[setSunColor]]
* [[setSunSize]]
* [[setTime]]
* [[setTrafficLightState]]
* [[setTrafficLightsLocked]]
* [[setVehiclesLODDistance]]
* [[setWeather]]
* [[setWeatherBlended]]
* [[setWindVelocity]]
* [[setWorldSoundEnabled]]
* [[setWorldSpecialPropertyEnabled]]
{{New items|3.0160|1.5.8|
*[[setColorFilter]]
|20718}}
* [[testLineAgainstWater]]
<noinclude>[[Category:Functions templates]]</noinclude>

OnElementDimensionChange

2021-01-03T12:41:44Z

Zver-CR: Created page with "__NOTOC__ {{Client event}} {{New feature/item|3.0160|1.5.8|20724|This event is triggered when the dimension of an element is changed using setElementDimension.}} ==Pa..."

__NOTOC__
{{Client event}}
{{New feature/item|3.0160|1.5.8|20724|This event is triggered when the dimension of an [[element]] is changed using [[setElementDimension]].}}

==Parameters==
<syntaxhighlight lang="lua">
int oldDimension, int newDimension
</syntaxhighlight>
*'''oldDimension''': an [[int]] representing the dimension the [[element]] was in before.
*'''newDimension''': an [[int]] representing the dimension the [[element]] is in now.

==Source==
The [[event system#Event source|source]] of this event is the [[element]] that changed its dimension.

==Example==
<syntaxhighlight lang="lua">
local vehicle = createVehicle ( 411, 0, 0, 3 )
setTimer ( setElementDimension, 1000, 1, vehicle, 10 )

addEventHandler ( "onElementDimensionChange", vehicle,
function ( oldDimension, newDimension )
outputChatBox ( inspect ( source ) .. "'s dimension changed from " .. oldDimension .. " to " .. newDimension )
end
)
</syntaxhighlight>

==Requirements==
{{Requirements|1.5.8-9.20724|n/a|}}

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

OnClientElementDimensionChange

2021-01-03T12:41:12Z

Zver-CR: Created page with "__NOTOC__ {{Client event}} {{New feature/item|3.0160|1.5.8|20724|This event is triggered when the dimension of an element is changed using setElementDimension.}} ==Pa..."

__NOTOC__
{{Client event}}
{{New feature/item|3.0160|1.5.8|20724|This event is triggered when the dimension of an [[element]] is changed using [[setElementDimension]].}}

==Parameters==
<syntaxhighlight lang="lua">
int oldDimension, int newDimension
</syntaxhighlight>
*'''oldDimension''': an [[int]] representing the dimension the [[element]] was in before.
*'''newDimension''': an [[int]] representing the dimension the [[element]] is in now.

==Source==
The [[event system#Event source|source]] of this event is the [[element]] that changed its dimension.

==Example==
<syntaxhighlight lang="lua">
local vehicle = createVehicle ( 411, 0, 0, 3 )
setTimer ( setElementDimension, 1000, 1, vehicle, 10 )

addEventHandler ( "onClientElementDimensionChange", vehicle,
function ( oldDimension, newDimension )
outputChatBox ( inspect ( source ) .. "'s dimension changed from " .. oldDimension .. " to " .. newDimension )
end
)
</syntaxhighlight>

==Requirements==
{{Requirements|n/a|1.5.8-9.20724|}}

==See Also==
===Client element events===
{{Client_element_events}}
===Client event functions===
{{Client_event_functions}}

GetSoundLevelData

2020-07-25T05:53:08Z

Zver-CR:

__NOTOC__
{{Client function}}
This function gets the left/right level from a [[sound]] [[element]].
{{New feature/item|3.0132|1.3.2||
If the element is a player, this function will use the players voice.
}}
==Syntax==
<syntaxhighlight lang="lua">int, int getSoundLevelData ( element theSound )</syntaxhighlight>
{{OOP||[[sound]]:getLevelData}}
===Required Arguments===
*'''theSound:''' the [[sound]] [[element]] which level data you want to return.

===Returns===
Returns a two ''integers'' in range from 0 to 32768.

==Example==
<syntaxhighlight lang="lua">
local soundHandler = playSound ( "sound.wav" )

function onSoundPlayRender ( )
if ( soundHandler ) then
local leftData, rightData = getSoundLevelData ( soundHandler )
if ( leftData ) then
dxDrawRectangle ( 0, 0, 64, leftData / 32768 * 256, tocolor ( 255, 0, 0 ) )
dxDrawRectangle ( 64, 0, 64, rightData / 32768 * 256, tocolor ( 0, 0, 255 ) )
end
end
end
addEventHandler ( "onClientRender", root, onSoundPlayRender )
</syntaxhighlight>

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

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.3.2|Added player element to use a players voice}}

==See Also==
{{Client_audio_functions}}

[[hu:getSoundLevelData]]
[[ar:getSoundLevelData]]
[[ro:getSoundLevelData]]

Template:New items

2020-07-03T11:12:36Z

Zver-CR:

<includeonly>{{#ifexpr:({{{1|}}})>{{Current Version}}|<div style='font-weight: bold;background:black;color:white;padding:2px; padding-left:8px;'>[[Beta Features|BETA]]: FROM VERSION {{{2}}} {{#if:{{{4|}}}|{{r|{{{4}}}}}|}} ONWARDS</div><div style='border: 2px solid black;padding: 3px;'>{{{3}}} </div>| {{{3}}}}}</includeonly><noinclude>Use this template for functions/events lists. In function and event pages use <nowiki>{{New feature/item}}</nowiki>. This will prevent wrong pages appear in changelog category.
=== Parameters ===
# Version float (value is compared with <code>></code> to <code><nowiki>{{Current Version}}</nowiki> = {{Current Version}}</code>)
# Version text (only visual, example: <code>{{Current Version|full}}</code>)
# Text
# Revision number (only visual)
[[Category:Utility templates]]</noinclude>

Template:Utility functions

2020-02-28T13:16:25Z

Zver-CR:

*[[addDebugHook]]
*[[base64Decode]]
*[[base64Encode]]
{{Bit_functions}}
*[[debugSleep]]
{{New items|3.0156|1.5.5|
*[[decodeString]]
*[[encodeString]]
|11849}}
*[[fromJSON]]
*[[getColorFromString]]
*[[getDevelopmentMode]]
*[[getDistanceBetweenPoints2D]]
*[[getDistanceBetweenPoints3D]]
*[[getEasingValue]]
*[[getFPSLimit]]
*[[getNetworkStats]]
*[[getNetworkUsageData]]
*[[getPerformanceStats]]
*[[getRealTime]]
*[[getServerConfigSetting]]
*[[getTickCount]]
*[[getTimerDetails]]
*[[getTimers]]
*[[gettok]]
*[[getUserdataType]]
*[[getVersion]]
*[[hash]]
*[[inspect]]
*[[interpolateBetween]]
*[[iprint]]
*[[isOOPEnabled]]
*[[isTimer]]
*[[killTimer]]
*[[md5]]
*[[passwordHash]]
*[[passwordVerify]]
*[[pregFind]]
*[[pregMatch]]
*[[pregReplace]]
*[[removeDebugHook]]
*[[resetTimer]]
*[[setDevelopmentMode]]
*[[setFPSLimit]]
*[[setServerConfigSetting]]
*[[setTimer]]
*[[sha256]]
*[[split]]
*[[teaDecode]]
*[[teaEncode]]
{{New items|3.0156|1.5.5|
*[[tocolor]]
|13977}}
*[[toJSON]]
*[[utfChar]]
*[[utfCode]]
*[[utfLen]]
*[[utfSeek]]
*[[utfSub]]

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

SetPedAnimation

2019-10-18T00:25:28Z

Zver-CR: Add 'retainPedState' to changelog

__NOTOC__
{{Server client function}}

Sets the current [[Animations|animation]] of a [[player]] or [[ped]]. Not specifying the type of animation will automatically cancel the current one.
{{Warning|It is possible that an animation will be cancelled if you use setElementFrozen on the ped, but this does not happen all the time.}}

==Syntax==
<syntaxhighlight lang="lua">
bool setPedAnimation ( ped thePed [, string block = nil, string anim = nil, int time = -1, bool loop = true, bool updatePosition = true,
bool interruptable = true, bool freezeLastFrame = true, int blendTime = 250, bool retainPedState = false ] )
</syntaxhighlight>
{{OOP||[[ped]]:setAnimation||getPedAnimation}}

===Required Arguments===
*'''thePed:''' the [[player]] or [[ped]] you want to apply an [[Animations|animation]] to.

===Optional Arguments===
{{OptionalArg}}
*'''block:''' the [[Animations|animation]] block's name.
*'''anim:''' the name of the [[Animations|animation]] within the block.
*'''time:''' how long the animation will run for in milliseconds.
*'''loop:''' indicates whether or not the animation will loop.
*'''updatePosition:''' will change the actual coordinates of the ped according to the animation. Use this for e.g. walking animations.
*'''interruptable:''' if set to ''false'' other tasks wont be able to interupt the animation. Setting this to 'false' also gives this function more power to override other animations that are running. For example, squatting after a jump can be terminated.
*'''freezeLastFrame:''' if set to ''true'' after animation the last frame will be frozen, otherwise the animation will end and controls will return.
*'''blendTime:''' how long the animation will mixed with the previous one in milliseconds.
{{New items|3.0157|1.5.7|
*'''retainPedState:''' will restore the task which was playing before calling this function. Useful for restoring the crouch task after animation ends. This may be extended in the future to support other states/tasks.
|16632}}

===Returns===
Returns ''true'' if succesful, ''false'' otherwise.

==Examples==

<section name="Server" class="server" show="true">
This example creates a ped, rotates him, and makes him walk:
<syntaxhighlight lang="lua">
function makePed()
local thePed = createPed(56, 1, 1, 4, 315)
setPedAnimation(thePed, "ped", "WOMAN_walknorm")
end
addCommandHandler("makemyped", makePed)
</syntaxhighlight>
</section>

<section name="Server" class="server" show="true">
This example makes the player sit down and stand up using the command /sit.
<syntaxhighlight lang="lua">
function toggleSit(thePlayer)
if not getElementData(thePlayer, "sitting") then
setPedAnimation(thePlayer, "ped", "seat_down", -1, false, false, false, false)
setElementData(thePlayer, "sitting", true)
else
-- If you use again this command then your character stand up
setPedAnimation(thePlayer)
removeElementData(thePlayer, "sitting")
end
end
addCommandHandler("sit", toggleSit)
</syntaxhighlight>
</section>

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.5.7-9.16632|Added retainPedState argument}}

==Issues==
{{Issues|
{{Issue|1110|retainPedState in setPedAnimation() does not work when latency reduction is set to 1}}
{{Issue|1090|retainPedState can reset a replaced crouch idle animation to default}}
{{Issue|953|setPedAnimation() "interrupt" and "time" has no effect in certain situations}}
{{Issue|512|setPedAnimation isn't synced properly on server side}}
{{Issue|467|Ped animations don't sync for new players}}
}}

==See Also==
{{Ped_functions}}
[[ru:setPedAnimation]]
[[HU:setPedAnimation]]

Undocumented Items

2019-08-25T19:26:49Z

Zver-CR: Remove documented functions

This page lists all MTA SA functions and events which don't have the necessary documentation for scripters to allow them to use the functions or events. Documenting these will require looking through the source code, which is available in the [https://github.com/multitheftauto/mtasa-blue MTA SA GitHub repository], to get the necessary parameters.
__NOTOC__
== Client functions that need documenting ==
*[[dxIsAspectRatioAdjustmentEnabled]]

== Server functions that need documenting ==
(None)

== Client events that need documenting ==
(None)

== Server events that need documenting ==
(None)

== Other undocumented pages ==
(None)

Undocumented Items

2019-05-26T21:25:49Z

Zver-CR: New functions & event

This page lists all MTA SA functions and events which don't have the necessary documentation for scripters to allow them to use the functions or events. Documenting these will require looking through the source code, which is available in the [https://github.com/multitheftauto/mtasa-blue MTA SA GitHub repository], to get the necessary parameters.
__NOTOC__
== Client functions that need documenting ==
*[[dxIsAspectRatioAdjustmentEnabled]]
*[[getVehicleComponentScale]]
*[[setVehicleComponentScale]]
*[[resetVehicleComponentScale]]
*[[guiGridListIsSortingEnabled]]
*[[guiGridListGetSelectionMode]]

== Server functions that need documenting ==
(None)

== Client events that need documenting ==
*[[onClientPaste]]

== Server events that need documenting ==
(None)

== Other undocumented pages ==
(None)

Template:Client vehicle functions

2019-05-26T21:23:52Z

Zver-CR: get/setVehicleModelDummyPosition

*[[addVehicleUpgrade]]
*[[attachTrailerToVehicle]]
*[[blowVehicle]]
*[[createVehicle]]
*[[detachTrailerFromVehicle]]
*[[fixVehicle]]
*[[getHeliBladeCollisionsEnabled]]
*[[getHelicopterRotorSpeed]]
*[[getOriginalHandling]]
*[[getTrainDirection]]
*[[getTrainPosition]]
*[[getTrainSpeed]]
{{New items|3.0160|1.6|
*[[getTrainTrack]]
|7485}}
*[[getVehicleAdjustableProperty]]
*[[getVehicleColor]]
*[[getVehicleCompatibleUpgrades]]
*[[getVehicleComponentPosition]]
*[[getVehicleComponentRotation]]
*[[getVehicleComponentVisible]]
*[[getVehicleComponents]]
*[[getVehicleController]]
*[[getVehicleCurrentGear]]
*[[getVehicleDoorOpenRatio]]
*[[getVehicleDoorState]]
*[[getVehicleEngineState]]
*[[getVehicleGravity]]
*[[getVehicleHandling]]
*[[getVehicleHeadLightColor]]
*[[getVehicleLandingGearDown]]
*[[getVehicleLightState]]
*[[getVehicleMaxPassengers]]
{{New items|3.0157|1.5.6|
*[[getVehicleModelDummyPosition]]
|14403}}
*[[getVehicleModelExhaustFumesPosition]]
*[[getVehicleModelFromName]]
*[[getVehicleName]]
*[[getVehicleNameFromModel]]
*[[getVehicleNitroCount]]
*[[getVehicleNitroLevel]]
*[[getVehicleOccupant]]
*[[getVehicleOccupants]]
*[[getVehicleOverrideLights]]
*[[getVehiclePaintjob]]
*[[getVehiclePanelState]]
*[[getVehiclePlateText]]
*[[getVehicleSirens]]
*[[getVehicleSirensOn]]
*[[getVehicleSirenParams]]
*[[getVehicleTowedByVehicle]]
*[[getVehicleTowingVehicle]]
{{Deprecated items|3.0156|1.5.6|
*[[getVehicleTurnVelocity]]
}}
*[[getVehicleTurretPosition]]
*[[getVehicleType]]
*[[getVehicleUpgradeOnSlot]]
*[[getVehicleUpgradeSlotName]]
*[[getVehicleUpgrades]]
*[[getVehicleVariant]]
*[[getVehicleWheelStates]]
*[[isTrainChainEngine]]
*[[isTrainDerailable]]
*[[isTrainDerailed]]
*[[isVehicleBlown]]
*[[isVehicleDamageProof]]
*[[isVehicleFuelTankExplodable]]
*[[isVehicleLocked]]
*[[isVehicleNitroActivated]]
*[[isVehicleNitroRecharging]]
*[[isVehicleOnGround]]
*[[isVehicleTaxiLightOn]]
{{New items|3.0156|1.5.5|
*[[isVehicleWheelOnGround]]
|11854}}
*[[isVehicleWindowOpen]]
*[[removeVehicleUpgrade]]
*[[resetVehicleComponentPosition]]
*[[resetVehicleComponentRotation]]
*[[setHeliBladeCollisionsEnabled]]
*[[setHelicopterRotorSpeed]]
*[[setTrainDerailable]]
*[[setTrainDerailed]]
*[[setTrainDirection]]
*[[setTrainPosition]]
*[[setTrainSpeed]]
{{New items|3.0160|1.6|
*[[setTrainTrack]]
|7485}}
*[[setVehicleAdjustableProperty]]
*[[setVehicleColor]]
*[[setVehicleComponentPosition]]
*[[setVehicleComponentRotation]]
*[[setVehicleComponentVisible]]
*[[setVehicleDamageProof]]
*[[setVehicleDirtLevel]]
*[[setVehicleDoorOpenRatio]]
*[[setVehicleDoorState]]
*[[setVehicleDoorsUndamageable]]
*[[setVehicleEngineState]]
*[[setVehicleFuelTankExplodable]]
*[[setVehicleGravity]]
{{New items|3.0156|1.5.5|
*[[setVehicleHandling]]
|12009}}
*[[setVehicleHeadLightColor]]
*[[setVehicleLandingGearDown]]
*[[setVehicleLightState]]
*[[setVehicleLocked]]
{{New items|3.0157|1.5.6|
*[[setVehicleModelDummyPosition]]
|14403}}
*[[setVehicleModelExhaustFumesPosition]]
*[[setVehicleNitroActivated]]
*[[setVehicleNitroCount]]
*[[setVehicleNitroLevel]]
*[[setVehicleOverrideLights]]
*[[setVehiclePaintjob]]
*[[setVehiclePanelState]]
*[[setVehiclePlateText]]
*[[setVehicleSirens]]
*[[setVehicleSirensOn]]
*[[setVehicleTaxiLightOn]]
{{Deprecated items|3.0156|1.5.6|
*[[setVehicleTurnVelocity]]
}}
*[[setVehicleTurretPosition]]
*[[setVehicleWheelStates]]
*[[setVehicleWindowOpen]]

<noinclude>[[ru:Template:RU/Client_vehicle_functions]]
[[Category:Functions templates]]</noinclude>

PlaySound3D

2019-04-07T05:40:17Z

Zver-CR: Undo revision 62446 by DezZolation (talk)

__NOTOC__
{{Client function}}
Creates a [[sound]] [[element]] in the GTA world and plays it immediately after creation for the local player. [[setElementPosition]] can be used to move the [[sound]] element around after it has been created. Remember to use [[setElementDimension]] after creating the sound to play it outside of dimension 0. 
 
{{Note|
*The only supported audio formats are MP3, WAV, OGG, RIFF, MOD, XM, IT and S3M.
*For performance reasons, when using playSound3D for effects that will be played lots (i.e. weapon fire), it is recommend that you convert your audio file to a one channel (mono) WAV with sample rate of 22050 Hz or less. Also consider adding a limit on how often the effect can be played e.g. once every 50ms.}}
==Syntax==
<syntaxhighlight lang="lua">element playSound3D ( string soundPath, float x, float y, float z, [ bool looped = false ] )</syntaxhighlight>
<syntaxhighlight lang="lua">element playSound3D ( string soundURL, float x, float y, float z, [ bool looped = false, bool throttled = true ] )</syntaxhighlight>
{{OOP||[[Sound|Sound3D]]}}
===Required Arguments===
*'''soundPath:''' the [[filepath]] to the sound file you want to play. (Sound file has to be predefined in the [[meta.xml]] file with <file /> tag. And also can use url instead of [[filepath]] )
*'''soundURL:''' the URL. (In this version the file does not has to be predefined in the [[meta.xml]] )
*'''x:''' a [[float]]ing point number representing the X coordinate on the map.
*'''y:''' a [[float]]ing point number representing the Y coordinate on the map.
*'''z:''' a [[float]]ing point number representing the Z coordinate on the map.

===Optional Arguments===
{{OptionalArg}}
*'''looped:''' a [[boolean]] representing whether the sound will be looped. To loop the sound, use ''true''.
{{New feature/item|3.0150|1.5||
*'''throttled:''' a [[boolean]] representing whether the sound will be throttled (i.e. given reduced download bandwidth). To throttle the sound, use ''true''.
}}

===Returns===
Returns a [[sound]] [[element]] if the sound was successfully created, ''false'' otherwise.

==Example==
This example creates a looping sound within a pizza shop. The pizza shop is in san fierro near pier 69
<section name="Example" class="client" show="true">
<syntaxhighlight lang="lua">
function onResourceStart()
local sound = playSound3D("sounds/song.mp3", 373.14, -125.21, 1001, true)
end
addEventHandler("onClientResourceStart", resourceRoot, onResourceStart)
</syntaxhighlight>
</section>
This example play internet radio in groove street.
<section name="Example 2" class="client" show="true" >
<syntaxhighlight lang="lua">
addEventHandler( 'onClientResourceStart', resourceRoot,
function( )
local uSound = playSound3D( 'http://193.34.51.25:80', 2498, -1659, 12 )
setSoundMaxDistance( uSound, 100 )
end
)
</syntaxhighlight>
</section>

==See Also==
{{Client_audio_functions}}
[[HU:playSound3D]]
[[AR:playSound3D]]
[[DE:playSound3D]]
[[RU:playSound3D]]

OnClientPedDamage

2019-01-16T23:01:45Z

Zver-CR:

__NOTOC__
{{Client event}}
This event is triggered whenever a [[ped]] is damaged.
{{Note|This event is only triggered for peds that are streamed in}}
==Parameters==
<syntaxhighlight lang="lua">
element attacker, int weapon, int bodypart [, float loss ]
</syntaxhighlight>

*'''attacker''': A [[player]] [[element]] representing the attacker or [[vehicle]] [[element]] (when a ped falls of a bike).
*'''weapon''': An integer representing the weapon ID the attacker used
*'''bodypart''': An integer representing the bodypart the ped was damaged
{{BodyParts}}
*'''loss''': A float representing the percentage of health the ped lost.

==Source==
The [[event system#Event source|source]] of this event is the [[ped]] that got damaged

==Cancel effect==
If this event is [[Event system#Canceling|canceled]], then any damaging effects to the ped will cease.

==Example==
This example cancels any damage done to peds
<syntaxhighlight lang="lua">
function cancelPedDamage ( attacker )
cancelEvent() -- cancel any damage done to peds
end
addEventHandler ( "onClientPedDamage", getRootElement(), cancelPedDamage )
</syntaxhighlight>

==Issues==
{{Issues|
{{Issue|8082|(Fixed in r9762) Custom weapons don't fully work with onClientPlayerDamage}}
}}

==See Also==
===Client ped events===
{{Client_ped_events}}
===Client event functions===
{{Client_event_functions}}

OnPlayerDamage

2019-01-16T23:01:32Z

Zver-CR:

__NOTOC__
{{Server event}}
This event is triggered when a player is damaged, in any way.

*This event is not triggered when attacked by a team member if friendly fire is enabled.
*Canceling this event has no effect. Cancel the client-side event [[onClientPlayerDamage]] instead.
*onPlayerDamage doesn't trigger if the damage kills the player, [[onPlayerWasted]] is called instead.

==Parameters==
<syntaxhighlight lang="lua">
player attacker, int attackerweapon, int bodypart, float loss
</syntaxhighlight>

*'''attacker''': a [[player]] element representing the player who was the attacker. If there was no attacker this returns false.
*'''attackerweapon''': an [[int]] representing the [[Weapons|attacker weapon]] or the [[Damage Types|damage type]].
*'''bodypart''': an [[int]] representing the bodypart ID the player was hit on when he got damaged.
{{BodyParts}}
*'''loss''': a [[float]] representing the percentage of health the player lost.

==Source==
The [[event system#Event source|source]] of this event is the [[player]] who was damaged.

==Example==
This example causes an instant kill when a player is shot in the head, and announces it in the chatbox.
<syntaxhighlight lang="lua">
--add an event handler for the onPlayerDamage event
function playerDamage_text ( attacker, weapon, bodypart, loss ) --when a player is damaged
if ( bodypart == 9 ) then -- if the body part is 9, i.e. the head
outputChatBox ( "Headshot!", getRootElement (), 255, 170, 0 ) --output "Headshot" into the chatbox
killPed ( source, attacker, weapon, bodypart ) -- and kill the player
end
end
addEventHandler ( "onPlayerDamage", getRootElement (), playerDamage_text )
</syntaxhighlight>

==Issues==
{{Issues|
{{Issue|6495|[Fixed in 1.3.3-5411] onPlayerDamage has wrong parameters if source on vehicle}}
{{Issue|8082|(Fixed in r9762) Custom weapons & objects don't fully work with ped damage events}}
}}

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