Multi Theft Auto: Wiki - User contributions [en]

User talk:Aintaro

2014-08-31T20:08:17Z

Aintaro: Created page with "How come (> 2-0 = 0) ? shouldn't that be 2?"

How come (> 2-0 = 0) ? shouldn't that be 2?

OOP Introduction

2014-08-31T20:07:24Z

Aintaro: /* Vectors */

{{Note_box|If you've contributed by editing and tweaking this forum page, if you've benefited from this tutorial, or if you have anything to say; please give me feedback in the forum link provided on the left.}}
This is a scripting tutorial explaining to you what object orientated programming is and teaching you how to use the OOP features of MTA. This was originally created by [[User:Qais|qaisjp]] ([[User talk:Qais|talk]]) 22:48, 8 June 2014 (UTC). [http://forum.mtasa.com/viewtopic.php?f=148&t=76388 Forum post.]

__TOC__
== Introduction to OOP ==
OOP stands for ''object orientated programming''. Three simple words, and you'll probably understand the last word the most. OOP is where all functions relating to a single instance are called on that instance, an instance being a creation of a class - an element class, a database class, a player, a vehicle. Originally, everything was ''procedural'', you had to do things like:
<syntaxhighlight lang="lua">
local vehicle = createVehicle(411, 0, 0, 3)
setVehicleDamageProof(vehicle, true)
setElementFrozen(vehicle, true)
setElementHealth(vehicle, 1000)
setElementVelocity(vehicle, 0.2, 0.2, 0.2)
destroyElement(vehicle)
</syntaxhighlight>
More often than not, you know what you're dealing with. The variable almost always links back to the type, you would name a vehicle that exploded as '''explodedVehicle''', or at-least in context you would understand that '''exploded''' implies a vehicle when in the '''onVehicleExplode''' event. So you have to write a long function ''and'' refer to the vehicle manually when working procedurally. Painful. Object orientated programming is very different to this and works with each "object" individually. Instead of having to call a function and referencing it inside the call, you actually call the function INSIDE the class.

You probably think everything you can create and pass to functions are elements. A vehicle is an element. A player is an element. Anything that is an element is also a class. Connections create an instance of a class, but "'''connection'''" isn't an element, it's an instance - an object. Throughout the tutorial when I say ''object'', I don't mean [[createObject]] (unless I actually mention it, but to make things clearer I will avoid mentioning physical objects as I write this article. Here is a fancy venn diagram I created to show the simple organisation of classes and elements.
[[File:Classes,_Elements_and_Problem_children.png|500px|left|venn diagram]]
The functions on the left are sorted to show what kind of category the returned value rests in. We've got Classes, Elements and "Problem children".
Problem children aren't real categories written in the code, just functions that break rules. Everything you can play with are classes: resources, vehicles, and teams.
All elements are classes, you can do: <syntaxhighlight lang="lua">destroyElement(ped)</syntaxhighlight> but you can't do: <syntaxhighlight lang="lua">destroyElement(resource)</syntaxhighlight>

Problem children are weird things. You can't do all the functions mentioned in (actually, all elements don't allow the full assortment of functions to be applied to them, but I've especially mentioned a few of them) in the "Element functions" section of the functions list, but you can do destroyElement() on them.
There are children of classes, for example, with players, the system goes like: ''Element -> Ped -> Player". All Players are Peds and all Peds are Elements. Not all Peds are Players, and certainly not all Elements are Players. The main point here is that almost everything that you can create or retrieve and then reuse later use a class.

Instead of the code before, the code could be replaced with this:
<syntaxhighlight lang="lua">
local vehicle = createVehicle(411, 0, 0, 3)
vehicle:setDamageProof(true)
vehicle:setFrozen(true)
vehicle:setHealth(1000)
vehicle:setVelocity(0.2, 0.2, 0.2)
vehicle:destroy()
</syntaxhighlight>
It works pretty similar to how a table works, it's just like customTable.setSomething() except the use of ''':''' makes Lua convert customTable:setSomething() convert to customTable.setSomething(customTable). This is pretty internal stuff about ''syntactic sugar'' and you don't really need to worry much about it.

Those functions are pretty useful, but there are more changes with OOP, I'll explain this below.

== Instantiation, variables ==
OOP removes the need to say the "create" part of the function, so instead of saying '''createVehicle''', you just say '''Vehicle'''. It works exactly the same way, it's almost just like doing '''Vehicle = createVehicle'''. Fancy, isn't it? The only difference here is that you miss out on the extra things offered, Vehicle doesn't have these extra things, but Player definitely does. For example, instead of doing getPlayerFromName(), you would do Player.getFromName(). It's a nice and simple way to organise functions.

Since OOP sits on top of procedural, many things have been inherited from the style of procedural, but to make things easier we have variables for all the functions that require a single input. We've shortened '''getElementDimension()''' down to '''element:getDimension()''', but we can also go one layer deeper: '''element.dimension'''. Yep, just like a variable. You can set this variable just like a normal variable and read from it just like a normal variable. Hey, you could even do this:
<syntaxhighlight lang="lua">local function incrementDimension()
local player = Player.getRandom() -- get a random player
player.dimension = player.dimension + 1 -- increment dimension
end
setTimer(incrementDimension, 60*1000, 10) -- set a timer for sixty thousand milliseconds, sixty seconds, one minute
</syntaxhighlight>
This code would take a random player and move them to the next dimension every minute for the next ten minutes.

== Vectors ==
player.position works too! But how do you change three arguments... using one variable? Vectors.
Vectors are very powerful classes and they come in multiple forms, for the purpose of this introduction I'll just cover a three dimensional vector in terms of elements. Using a vector is very simple, and is, of course, optional. Wherever you can currently use positions, you can use a vector.

So, this is a simple example of creating a vehicle and moving it to the the centre of the map using vectors
<syntaxhighlight lang="lua">
-- First, create a three-dimensional vector
local position = Vector3(300, -200, 2) -- some place far away
local vehicle = Vehicle(411, position) -- create a vehicle at the position
vehicle.position = centreOfMap - Vector3(300, -200, 0) -- move the vehicle two units above the center of the map
</syntaxhighlight>

Yes, I used the negative sign. Vectors aren't just fancy ways for positions or 3d rotations or whatever, you can use maths on them. The ''special'' maths hasn't been documented yet, but I'll try and work on that. So, as you can see in line one, I created a 3D vector at ''300, -200, 2'' and then in line two I created the vehicle at that position.

'''vehicle.position''' returned a vector and also takes a vector - it is pretty much setElementPosition() without the "()". Just a simple variable; so, in line three, I changed the vector value of the position of the vehicle. This is where the maths happened, in simple terms this is what is going on:
<syntaxhighlight lang="lua">
x = 300 - 300 (> 300-300 = 0)
y = -200 - -200 (> -200+200 = 0)
z = 2 - 0 (> 2-0 = 0)
</syntaxhighlight>

Vector maths is slightly complicated but it definitely allows for a wide variety of mathematical magic. Check out the useful links below related to Vectors and Matrices (Matrices = plural form of Matrix) to understand more about how this works.

== Useful links ==
Other useful OOP related tutorials:
* [[Manipulating Vectors]]
* [[Manipulating Matrices]]

[[Category:Incomplete]]
[[Category:Tutorials]]

TriggerServerEvent

2014-07-15T12:49:12Z

Aintaro: /* Example */

__NOTOC__
{{Client function}}
This function triggers an event previously registered on the server. This is the primary means of passing information between the client and the server. Servers have a similar [[triggerClientEvent]] function that can do the reverse. You can treat this function as if it was an asynchronous function call, using [[triggerClientEvent]] to pass back any returned information if necessary.

Almost any data types can be passed as expected, including [[element]]s and complex nested [[table]]s. Non-element MTA data types like xmlNodes or resource pointers will not be able to be passed as they do not necessarily have a valid representation on the client.

Events are sent reliably, so the server will receive them, but there may be (but shouldn't be) a significant delay before they are received. You should take this into account when using them.

Keep in mind the bandwidth issues when using events - don't pass a large list of arguments unless you really need to. It is marginally more efficient to pass one large event than two smaller ones.
{{Warning|You should use the global variable [[Predefined_variables_list|''client'']] serverside instead of passing the localPlayer by parameter or source. Otherwise event faking (passing another player instead of the localPlayer) would be possible. More information at [[addEventHandler]]}}
==Syntax==
<syntaxhighlight lang="lua">
bool triggerServerEvent ( string event, element theElement, [arguments...] )
</syntaxhighlight>

===Required Arguments===
*'''event:''' The name of the event to trigger server-side. You should register this event with [[addEvent]] and add at least one event handler using [[addEventHandler]].
*'''theElement:''' The element that is the [[Event system#Event handlers|source]] of the event.
{{Note|To save server CPU, you should avoid setting '''theElement''' to the [[root element]] where possible. Using [[GetThisResource|resourceRoot]] is usually sufficient if the event is handled by the same resource on the server.}}
===Optional Arguments===
*'''arguments...:''' A list of arguments to trigger with the event. You can pass any lua data type (except functions). You can also pass [[element]]s.

===Returns===
Returns ''true'' if the event trigger has been sent, ''false'' if invalid arguments were specified.

==Example==
This example shows how you can pass a simple "Hello World" message from the client to the server using an event.

<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
function greetingHandler ( message )
if (client == source) then -- security check if the client is equal to the source that is going to execute the event
-- the predefined variable 'client' points to the player who triggered the event and should be used due to security issues
outputChatBox ( "The client says: " .. message, client )
end
end
addEvent( "onGreeting", true )
addEventHandler( "onGreeting", root, greetingHandler )
</syntaxhighlight>
</section>
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
function greetingCommand ( commandName )
triggerServerEvent ( "onGreeting", localPlayer, "Hello World!" )
-- localPlayer instead of root makes the client player the 'source' on the server function, eliminating the need for an additional player argument to be transferred.
end
addCommandHandler ( "greet", greetingCommand )
</syntaxhighlight>
</section>

When the command "greet" is executed (by typing it in the server console or the player's console), the clients ''greetingCommand'' function is called. This triggers the server-side event ''onGreeting'' with the string ''"Hello World!"''. This event is then handled by the ''greetingHandler'' function server-side which then displays the message.

==See Also==
{{Client_event_functions}}
[[ru:triggerServerEvent]]

BindKey

2014-07-12T13:47:51Z

Aintaro: /* Example */

{{Server client function}}
__NOTOC__
Binds a player's key to a handler function or command, which will be called when the key is pressed.

==Syntax==
<section name="Server - Syntax 1" class="server" show="true">
<syntaxhighlight lang="lua">bindKey ( player thePlayer, string key, string keyState, function handlerFunction, [ var arguments, ... ] )</syntaxhighlight>

===Required Arguments===
*'''thePlayer:''' The player you wish to bind the key of.
*'''key:''' The key or control you wish to bind to the command. See [[key names]] for a list of possible keys and [[control names]] for a list of possible controls.
*'''keyState:''' A string that has one of the following values:
**'''"up":''' If the bound key should trigger the function when the key is released
**'''"down":''' If the bound key should trigger the function when the key is pressed
**'''"both":''' If the bound key should trigger the function when the key is pressed or released
*'''handlerFunction:''' The function that will be triggered when the player's key is pressed. This function should have the form:
:<syntaxhighlight lang="lua">function functionName ( player keyPresser, string key, string keyState, [ var arguments, ... ] )</syntaxhighlight>
:The values passed to this function are:
:*'''keyPresser:''' The player who pressed the key
:*'''key:''' The key that was pressed
:*'''keyState:''' The state of the key that was pressed, ''down'' if it was pressed, ''up'' if it was released.
:*'''arguments''' The optional arguments you specified when calling [[bindKey]] (see below).
</section>

{{New feature|3|1.0|
<section name="Server - Syntax 2" class="server" show="true">
This alternative syntax allows you to bind a key with a command. This will also allow users to customize the control in their Settings menu. Use in conjunction with [[addCommandHandler]] to add handler functions to the keybind.

<syntaxhighlight lang="lua">bindKey ( player thePlayer, string key, string keyState, string commandName, [ string arguments ] )</syntaxhighlight>

===Required Arguments===
*'''thePlayer:''' The player you wish to bind the key of.
*'''key:''' The key or control you wish to bind to the command. See [[key names]] for a list of possible keys.
*'''keyState:''' A string that has one of the following values:
**'''"up":''' If the bound key should trigger the function when the key is released
**'''"down":''' If the bound key should trigger the function when the key is pressed
**'''"both":''' If the bound key should trigger the function when the key is pressed or released
*'''commandName:''' The name of the command that the key should be binded to.
===Optional Arguments===
*'''arguments''' Space delimited arguments that are entered as if one was typing the command.
</section>
}}

<section name="Client - Syntax 1" class="client" show="true">
<syntaxhighlight lang="lua">bindKey ( string key, string keyState, function handlerFunction, [ var arguments, ... ] ) </syntaxhighlight>

===Required Arguments===
*'''key:''' The key or control you wish to bind to the command. See [[key names]] for a list of possible keys and [[control names]] for a list of possible controls.
*'''keyState:''' A string that has one of the following values:
**'''"up":''' If the bound key should trigger the function when the key is released
**'''"down":''' If the bound key should trigger the function when the key is pressed
**'''"both":''' If the bound key should trigger the function when the key is pressed or released

*'''handlerFunction:''' The function that will be triggered when the player's key is pressed. This function should have the form:
:<syntaxhighlight lang="lua">function functionName ( string key, string keyState, [ var arguments, ... ] )</syntaxhighlight>
:The values passed to this function are:
:*'''key:''' The key that was pressed
:*'''keyState:''' The state of the key that was pressed, ''down'' if it was pressed, ''up'' if it was released.
:*'''arguments''' The optional arguments you specified when calling [[bindKey]] (see below).
</section>

{{New feature|3|1.0|
<section name="Client - Syntax 2" class="client" show="true">
This alternative syntax allows you to bind a key with a command. This will also allow users to customize the control in their Settings menu. Use in conjunction with [[addCommandHandler]] to add handler functions to the keybind.

<syntaxhighlight lang="lua">bindKey ( string key, string keyState, string commandName, [ string arguments ] )</syntaxhighlight>

===Required Arguments===
*'''key:''' The key or control you wish to bind to the command. See [[key names]] for a list of possible keys.
*'''keyState:''' A string that has one of the following values:
**'''"up":''' If the bound key should trigger the function when the key is released
**'''"down":''' If the bound key should trigger the function when the key is pressed
**'''"both":''' If the bound key should trigger the function when the key is pressed or released
*'''commandName:''' The name of the command that the key should be binded to.
*'''arguments''' Space delimited arguments that are entered as if one was typing the command.
</section>
}}

===Optional Arguments===
{{OptionalArg}}
*'''arguments:''' Any arguments you may want to pass to the function when the key is pressed by the user. Any number of arguments of can be specified, each being passed to the designated function. You may not pass functions.

===Issues===
{{Issues|
{{Issue|7948|bindKey using a command and control name doesn't work}}
}}

==Example==
Example 1
<section name="Server" class="server" show="true">
This example will bind a player's 'F1' key and 'fire' control to 1 input function.
<syntaxhighlight lang="lua">
function funcInput ( player, key, keyState )
local state = "let go of"
if ( keyState == "down" ) then
state = "pressed"
end
outputChatBox ( getPlayerName ( player) .. " " .. state .. " the " .. key .. " key!" )
end

function bindTheKeys ( player, commandName )
bindKey ( player, "F1", "down", funcInput ) -- bind the player's F1 down key
bindKey ( player, "F1", "up", funcInput ) -- bind the player's F1 up key
bindKey ( player, "fire", "both", funcInput ) -- bind the player's fire down and up control
end
addCommandHandler ( "bindme", bindTheKeys )
</syntaxhighlight>
</section>

Example 2
<section name="Client" class="client" show="true">
This example will bind a player's 'F1' key and 'fire' control to 1 input function, clientside.
<syntaxhighlight lang="lua">
function funcInput ( key, keyState )
local state = "let go of"
if ( keyState == "down" ) then
state = "pressed"
end
outputChatBox ( "You " .. state .. " the " .. key .. " key!" )
end

function bindTheKeys ()
bindKey ( "F1", "down", funcInput ) -- bind the player's F1 down key
bindKey ( "F1", "up", funcInput ) -- bind the player's F1 up key
bindKey ( "fire", "both", funcInput ) -- bind the player's fire down and up control
end
addCommandHandler ( "bindme", bindTheKeys )
</syntaxhighlight>
</section>

<section name="Server" class="server" show="true">
This example says how cool <s>Robpol86</s> <s>Ransom</s> Aintaro is if players wants to move.
<syntaxhighlight lang="lua">
function fanFunction()
bindKey (source,"forwards","down",
function(player,key,state)
outputChatBox (getPlayerName (player) .. "#FFFF00 thinks Aintaro is cool.",getRootElement(),255,255,0,true)
end
)
end
addEventHandler ("onPlayerLogin",getRootElement(),fanFunction)
</syntaxhighlight>
</section>

==See Also==
{{Input functions}}

TriggerClientEvent

2014-06-29T23:11:16Z

Aintaro: /* Example 2 */

__NOTOC__
{{Server function}}
This function triggers an event previously registered on a client. This is the primary means of passing information between the server and the client. Clients have a similar [[triggerServerEvent]] function that can do the reverse. You can treat this function as if it was an asynchronous function call, using [[triggerServerEvent]] to pass back any returned information if necessary.

Almost any data types can be passed as expected, including [[element]]s and complex nested [[table]]s. Non-element MTA data types like xmlNodes or resource pointers will not be able to be passed as they do not necessarily have a valid representation on the client.

Events are sent reliably, so clients will receive them, but there may be (but shouldn't be) a significant delay before they are received. You should take this into account when using them.

Keep in mind the bandwidth issues when using events - don't pass a large list of arguments unless you really need to. It is marginally more efficient to pass one large event than two smaller ones.
==Syntax==
<syntaxhighlight lang="lua">
bool triggerClientEvent ( [table/element sendTo=getRootElement()], string name, element sourceElement, [arguments...] )
</syntaxhighlight>

===Required Arguments===
*'''name:''' The name of the event to trigger client side. You should register this event with [[addEvent]] and add at least one event handler using [[addEventHandler]].
*'''sourceElement:''' The element that is the [[Event system#Event handlers|source]] of the event.
{{Note|To save client CPU, you should avoid setting '''sourceElement''' to the [[root element]] where possible. Using [[GetThisResource|resourceRoot]] is usually sufficient if the event is handled by the same resource on the client.}}

===Optional Arguments===
{{OptionalArg}}
*'''sendTo:''' The event will be sent to all [[player]]s that are children of the specified element. By default this is the root element, and hence the event is sent to all players. If you specify a single player it will just be sent to that player. This argument can also be a table of player elements.
*'''arguments...:''' A list of arguments to trigger with the event. You can pass any lua data type (except functions). You can also pass [[element]]s.

===Returns===
Returns ''true'' if the event trigger has been sent, ''false'' if invalid arguments were specified.

===Issues===
{{Issues|
{{Issue|4298|triggerClientEvent() doesn't pass large numbers or floats accurately}}
}}

==Example==
===Example 1===
This example shows how you can pass a simple "Hello World" message from the server to the all the clients using an event.

<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
function greetingHandler ( message )
outputChatBox ( "The server says: " .. message )
end
addEvent( "onGreeting", true )
addEventHandler( "onGreeting", localPlayer, greetingHandler )
</syntaxhighlight>
</section>
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
function greetingCommand ( playerSource, commandName )
triggerClientEvent ( playerSource, "onGreeting", playerSource, "Hello World!" )
end
addCommandHandler ( "greet", greetingCommand )
</syntaxhighlight>
</section>

When the command "greet" is executed (by typing it in the server console or the player's console), the server's ''greetingCommand'' function is called. This triggers the client side event ''onGreeting'' with the string ''"Hello World!"''. This event is then handled by the ''greetingHandler'' function client side which then displays the message.

===Example 2===
This example shows how you can pass a simple "Hello World" message from the server to '''a single''' client using an event.

<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
function greetingHandler ( message )
outputChatBox ( "The server says: " .. message )
end
addEvent( "onGreeting", true )
addEventHandler( "onGreeting", localPlayer, greetingHandler )
</syntaxhighlight>
</section>
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
function greetingCommandOne ( playerSource, commandName, playerName )
if playerName then
local thePlayer = getPlayerFromName ( playerName )
if thePlayer then
triggerClientEvent ( thePlayer, "onGreeting", thePlayer, "Hello World!" )
else
-- invalid player name specified
end
else
-- No player name specified
end
end
addCommandHandler ( "greet_one", greetingCommandOne )
</syntaxhighlight>
</section>

This works like the first example except an extra ''thePlayer'' argument is specified for triggerClientEvent.

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.3.0-9.04570|Added option to use a list of player elements for the 'sendTo' argument}}

==See Also==
{{Event functions}}
[[ru:triggerClientEvent]]

TriggerClientEvent

2014-06-29T23:10:35Z

Aintaro: /* Example 1 */

__NOTOC__
{{Server function}}
This function triggers an event previously registered on a client. This is the primary means of passing information between the server and the client. Clients have a similar [[triggerServerEvent]] function that can do the reverse. You can treat this function as if it was an asynchronous function call, using [[triggerServerEvent]] to pass back any returned information if necessary.

Almost any data types can be passed as expected, including [[element]]s and complex nested [[table]]s. Non-element MTA data types like xmlNodes or resource pointers will not be able to be passed as they do not necessarily have a valid representation on the client.

Events are sent reliably, so clients will receive them, but there may be (but shouldn't be) a significant delay before they are received. You should take this into account when using them.

Keep in mind the bandwidth issues when using events - don't pass a large list of arguments unless you really need to. It is marginally more efficient to pass one large event than two smaller ones.
==Syntax==
<syntaxhighlight lang="lua">
bool triggerClientEvent ( [table/element sendTo=getRootElement()], string name, element sourceElement, [arguments...] )
</syntaxhighlight>

===Required Arguments===
*'''name:''' The name of the event to trigger client side. You should register this event with [[addEvent]] and add at least one event handler using [[addEventHandler]].
*'''sourceElement:''' The element that is the [[Event system#Event handlers|source]] of the event.
{{Note|To save client CPU, you should avoid setting '''sourceElement''' to the [[root element]] where possible. Using [[GetThisResource|resourceRoot]] is usually sufficient if the event is handled by the same resource on the client.}}

===Optional Arguments===
{{OptionalArg}}
*'''sendTo:''' The event will be sent to all [[player]]s that are children of the specified element. By default this is the root element, and hence the event is sent to all players. If you specify a single player it will just be sent to that player. This argument can also be a table of player elements.
*'''arguments...:''' A list of arguments to trigger with the event. You can pass any lua data type (except functions). You can also pass [[element]]s.

===Returns===
Returns ''true'' if the event trigger has been sent, ''false'' if invalid arguments were specified.

===Issues===
{{Issues|
{{Issue|4298|triggerClientEvent() doesn't pass large numbers or floats accurately}}
}}

==Example==
===Example 1===
This example shows how you can pass a simple "Hello World" message from the server to the all the clients using an event.

<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
function greetingHandler ( message )
outputChatBox ( "The server says: " .. message )
end
addEvent( "onGreeting", true )
addEventHandler( "onGreeting", localPlayer, greetingHandler )
</syntaxhighlight>
</section>
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
function greetingCommand ( playerSource, commandName )
triggerClientEvent ( playerSource, "onGreeting", playerSource, "Hello World!" )
end
addCommandHandler ( "greet", greetingCommand )
</syntaxhighlight>
</section>

When the command "greet" is executed (by typing it in the server console or the player's console), the server's ''greetingCommand'' function is called. This triggers the client side event ''onGreeting'' with the string ''"Hello World!"''. This event is then handled by the ''greetingHandler'' function client side which then displays the message.

===Example 2===
This example shows how you can pass a simple "Hello World" message from the server to '''a single''' client using an event.

<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
function greetingHandler ( message )
outputChatBox ( "The server says: " .. message )
end
addEvent( "onGreeting", true )
addEventHandler( "onGreeting", getRootElement(), greetingHandler )
</syntaxhighlight>
</section>
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
function greetingCommandOne ( playerSource, commandName, playerName )
if playerName then
local thePlayer = getPlayerFromName ( playerName )
if thePlayer then
triggerClientEvent ( thePlayer, "onGreeting", getRootElement(), "Hello World!" )
else
-- invalid player name specified
end
else
-- No player name specified
end
end
addCommandHandler ( "greet_one", greetingCommandOne )
</syntaxhighlight>
</section>

This works like the first example except an extra ''thePlayer'' argument is specified for triggerClientEvent.

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.3.0-9.04570|Added option to use a list of player elements for the 'sendTo' argument}}

==See Also==
{{Event functions}}
[[ru:triggerClientEvent]]

DxDrawImage

2014-06-26T11:44:23Z

Aintaro: /* Syntax */

__NOTOC__
{{Client function}}

Draws an image on the screen for a single frame. In order for the image to stay visible continuously, you need to call this function with the same parameters on each frame update (see [[onClientRender]]).<br/>
Image files should ideally have dimensions that are a power of two, to prevent possible blurring.<br/>
<b>Power of two: 2px, 4px, 8px, 16px, 32px, 64px, 128px, 256px, 512px, 1024px...</b>
{{Note|To help prevent edge artifacts when drawing textures, set '''textureEdge''' to '''"clamp"''' when calling [[dxCreateTexture]]}}
==Syntax==
<syntaxhighlight lang="lua">
bool dxDrawImage ( float posX, float posY, float width, float height, mixed image [, float rotation = 0, float rotationCenterOffsetX = 0,
float rotationCenterOffsetY = 0, int color = tocolor(255,255,255,255), bool postGUI = false ] )
</syntaxhighlight>

===Required Arguments===
*'''posX:''' the absolute X coordinate of the top left corner of the image
*'''posY:''' the absolute Y coordinate of the top left corner of the image
*'''width:''' the absolute width of the image
*'''height:''' the absolute height of the image
*'''image:''' Either a [[material]] element or a [[filepath]] of the image which is going to be drawn. (.dds images are also supported). Image files should ideally have dimensions that are a power of two, to prevent possible blurring.

===Optional Arguments===
*'''rotation:''' the rotation, in degrees for the image.
*'''rotationCenterOffsetX:''' the absolute X offset from the image center for which to rotate the image from.
*'''rotationCenterOffsetY:''' the absolute Y offset from the image center for which to rotate the image from.
*'''color:''' Tints the image with a value produced by [[tocolor]] or hexadecimal number in format: 0xAARRGGBB (RR = red, GG = green, BB = blue, AA = alpha).
*'''postgui :''' A bool representing whether the image should be drawn on top of or behind any ingame GUI (rendered by CEGUI).

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

==Example==
Example of a pendulum swinging from the top of the screen, made using dxDrawImage.
<syntaxhighlight lang="lua">
local screenWidth,screenHeight = guiGetScreenSize() -- Get screen resolution.

function renderDisplay ( )
local seconds = getTickCount() / 1000
local angle = math.sin(seconds) * 80
-- This will draw the graphic file 'arrow.png' at the top middle of the screen
-- using the size of 100 pixels wide, and 240 pixels high.
-- The center of rotation is at the top of the image.
dxDrawImage ( screenWidth/2 - 50, 0, 100, 240, 'arrow.png', angle, 0, -120 )
end

function HandleTheRendering ( )
addEventHandler("onClientRender", getRootElement(), renderDisplay) -- Keep everything visible with onClientRender.
end
addEventHandler("onClientResourceStart",resourceRoot, HandleTheRendering)
</syntaxhighlight>

==See Also==
{{Drawing_functions}}

OnElementDataChange

2014-06-25T14:10:46Z

Aintaro: /* Example */

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

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

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

==Global parameters==
*'''source''': The [[event system#Event source|source]] of this event is the [[element]] whose element data changed
*'''client''': The [[event system#Event client|client]] global variable is set to the client that called [[setElementData]], or nil if it was called on the server.
*'''sourceResource''': The [[resource]] which changed the element data. (Only works in versions above 1.3.4-5937)

==Cancelling==
This event cannot be cancelled using [[cancelEvent]]. To reverse the effect, use [[setElementData]] with the old value. See Example.

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

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

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

This example checks and possibly reverses an element's data change.

<syntaxhighlight lang="lua">
function checkChange(dataName,oldValue)
if client then
-- The client can only set 'special_thing' on its own player
if (dataName == "special_thing" and client ~= source) then
outputChatBox( "Illegal setting of "..tostring(dataName).."' by '"..tostring(getPlayerName(client)) )
setElementData( source, dataName, oldValue ) -- Set back the original value
end
end
end
addEventHandler("onElementDataChange",getRootElement(),checkChange)
</syntaxhighlight>
</section>
{{See also/Server event|Element events}}

TextDisplayAddObserver

2014-06-23T15:35:57Z

Aintaro: /* Example */

__NOTOC__
{{Server function}}
This function adds a [[player]] as an observer of a [[textdisplay]]. This allows the [[player]] to see any [[textitem]]s that the [[textdisplay]] contains.

==Syntax==
<syntaxhighlight lang="lua">void textDisplayAddObserver ( textdisplay display, player playerToAdd )</syntaxhighlight>

===Required Arguments===

* '''display''': The [[textdisplay]] to add the [[player]] to as an observer.
* '''playerToAdd''': The [[player]] that should observe the [[textdisplay]].

==Example==
<syntaxhighlight lang="lua">
function MyTestTextFunction ()
display = textCreateDisplay () -- create a new display, store the reference in a variable called display
textDisplayAddObserver ( display, thePlayer ) -- add an observer to it
text = textCreateTextItem ( "Hello World", 0.5, 0.5, "medium", 255, 0, 0, 255, 2, "left", "top", 255) --red text of 24pt at the center of your screen
textDisplayAddText ( display, text ) -- Add the text item to the text display
end
</syntaxhighlight>

==See Also==
{{Text functions}}