AttachElementToElement: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
No edit summary
m (Changed "DeprecatedWithAlt" template to "Deprecated")
 
(22 intermediate revisions by 11 users not shown)
Line 1: Line 1:
{{Needs Checking|What kinds of elements can be attached together? --[[User:Jbeta|jbeta]]}}
__NOTOC__  
__NOTOC__  
This function attaches one element to another, so that the second one follows the first whenever it moves.
{{Server client function}}
{{Deprecated|attachElements|}}
 
This function attaches one element to another, so that the first one follows the second whenever it moves.  
 
If an attempt is made to attach two elements that are already attached the opposite way (eg theElement becomes theAttachToElement and vice versa), the 1st attachment order is automatically detached in favor of the 2nd attachment order. For example, if carA was attached to carB, now carB is attached to carA. Also, an element cannot be attached to two separate elements at one time. For example, two cars can be attached to one single car, but one single car cannot be attached to two separate cars. If you attempt to do this, the existing attachment will automatically be dropped in favor of the new attachment. For example, if carA is asked to attached to carB then carC, it is only attached to carC.
 
This is not compatible with all elements.  The following elements are compatible:
* [[Marker|Markers]]
* [[Blip|Blips]]
* [[Object|Objects]]
* [[Player|Players]]
* [[Vehicle|Vehicles]]


==Syntax==  
==Syntax==  
<!-- NOTE: don't use 'special' names for variable names, e.g. you shouldn't be writing things like 'player player, vehicle vehicle', instead write something like 'player thePlayer, vehicle vehicleToGetInto'. This is less confusing and prevents the syntax highlighting being odd -->
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
bool attachElementToElement ( element theElement, element theAttachToElement, [ float xOffset, float yOffset, float zOffset ] )
bool attachElementToElement ( element theElement, element theAttachToElement, [ float xPosOffset, float yPosOffset, float zPosOffset, float xRotOffset, float yRotOffset, float zRotOffset ] )
</syntaxhighlight>  
</syntaxhighlight>  


===Required Arguments===  
===Required Arguments===  
<!-- List each argument one per line. This should be the argument's name as in the argument list above, NOT the argument's data type -->
*'''theElement:''' The element to be attached.
*'''theElement:''' The element to be attached.
*'''theAttachToElement:''' The element to attach the first to.
*'''theAttachToElement:''' The element to attach the first to.


<!-- Only include this section below if there are optional arguments -->
===Optional Arguments===  
===Optional Arguments===  
{{OptionalArg}}  
{{OptionalArg}}  
*'''xOffset:''' The x offset, if you want the elements to be a certain distance from one another (default 0).
*'''xPosOffset:''' The x offset, if you want the elements to be a certain distance from one another (default 0).
*'''yOffset:''' The y offset (default 0).
*'''yPosOffset:''' The y offset (default 0).
*'''zOffset:''' The z offset (default 0).
*'''zPosOffset:''' The z offset (default 0).
*'''xRotOffset:''' The x rotation offset (default 0).
*'''yRotOffset:''' The y rotation offset (default 0).
*'''zRotOffset:''' The z rotation offset (default 0).


===Returns===
===Returns===
<!-- Make this descriptive. Explain what cases will return false. If you're unsure, add a tag to it so we can check -->
Returns ''true'' if the attaching process was successful, ''false'' otherwise.
Returns ''true'' if the attaching process was successful, ''false'' otherwise.


==Example==  
==Example==  
<!-- Explain what the example is in a single sentance -->
<section name="Server" class="server" show="true">
This example does...
'''Example 1:''' This example attaches a marker to the player who steals the Mr. Whoopee:
<!-- Add the code below, an emphasis should be on making it clear, not optimized. You could provide two versions if you wish, one clear and well commented, the other optimized -->
<syntaxhighlight lang="lua">
-- create the vehicle
local vehicleMrWhoopee = createVehicle ( 423, 237.472 -54.225 1.518, 0, 354.488, 0 )
 
function onMrWhoopeeEnter ( thePlayer, seat, jackedPlayer )
    outputChatBox ( getClientName ( thePlayer ) .. " stole the Whoopee!", getRootElement (), 255, 0, 0 )
    -- create the marker to attach
    local arrowMarker = createMarker ( 0, 0, 0, "arrow", .75, 255, 0, 0, 170 )
    -- attach the marker to the player with a vertical offset of 2 units
    attachElementToElement ( arrowMarker, thePlayer, 0, 0, 2 )
end
 
-- attach it to an event
addEventHandler ( "onVehicleEnter", vehicleMrWhoopee, onMrWhoopeeEnter )
</syntaxhighlight>
'''Example 2:''' This function adds a tank on top of a player (for extra defense):
<syntaxhighlight lang="lua">
function tankHat( source, commandName )
      local x, y, z = getElementPosition( source ) --Get the players position
      local tank = createVehicle( 432, x, y, z + 5 ) --Create a tank
      attachElementToElement( tank, source, 0, 0, 5 ) --Attach the tank to the player.
end
addCommandHandler( "hat", tankHat )
</syntaxhighlight>
</section>
<section name="Client" class="client" show="false">
'''Example 3:''' This function adds a tank on top of a player (for extra defense), clientside.  This means it will be invisible to other players.
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
--This line does...
function tankHat( commandName )
blabhalbalhb --abababa
      local x, y, z = getElementPosition( source ) --Get the players position
--This line does this...
      local tank = createVehicle( 432, x, y, z + 5 ) --Create a tank
mooo
      attachElementToElement( tank, source, 0, 0, 5 ) --Attach the tank to the player.
end
addCommandHandler( "hat", tankHat )
</syntaxhighlight>
</syntaxhighlight>
</section>


==See Also==
==See Also==
<!-- Change FunctionArea to the area that this function is in on the main function list page, e.g. Server, Player, Vehicle etc -->
{{Element functions}}
{{Element_functions}}
[[Category:Incomplete]] <!-- leave this unless you complete the function -->

Latest revision as of 16:27, 13 February 2015

Emblem-important.png This function is deprecated. This means that its use is discouraged and that it might not exist in future versions.
Please use attachElements instead.


This function attaches one element to another, so that the first one follows the second whenever it moves.

If an attempt is made to attach two elements that are already attached the opposite way (eg theElement becomes theAttachToElement and vice versa), the 1st attachment order is automatically detached in favor of the 2nd attachment order. For example, if carA was attached to carB, now carB is attached to carA. Also, an element cannot be attached to two separate elements at one time. For example, two cars can be attached to one single car, but one single car cannot be attached to two separate cars. If you attempt to do this, the existing attachment will automatically be dropped in favor of the new attachment. For example, if carA is asked to attached to carB then carC, it is only attached to carC.

This is not compatible with all elements. The following elements are compatible:

Syntax

bool attachElementToElement ( element theElement, element theAttachToElement, [ float xPosOffset, float yPosOffset, float zPosOffset, float xRotOffset, float yRotOffset, float zRotOffset ] )

Required Arguments

  • theElement: The element to be attached.
  • theAttachToElement: The element to attach the first to.

Optional Arguments

NOTE: When using optional arguments, you might need to supply all arguments before the one you wish to use. For more information on optional arguments, see optional arguments.

  • xPosOffset: The x offset, if you want the elements to be a certain distance from one another (default 0).
  • yPosOffset: The y offset (default 0).
  • zPosOffset: The z offset (default 0).
  • xRotOffset: The x rotation offset (default 0).
  • yRotOffset: The y rotation offset (default 0).
  • zRotOffset: The z rotation offset (default 0).

Returns

Returns true if the attaching process was successful, false otherwise.

Example

Click to collapse [-]
Server

Example 1: This example attaches a marker to the player who steals the Mr. Whoopee: 

-- create the vehicle
local vehicleMrWhoopee = createVehicle ( 423, 237.472 -54.225 1.518, 0, 354.488, 0 )

function onMrWhoopeeEnter ( thePlayer, seat, jackedPlayer )
    outputChatBox ( getClientName ( thePlayer ) .. " stole the Whoopee!", getRootElement (), 255, 0, 0 )
    -- create the marker to attach
    local arrowMarker = createMarker ( 0, 0, 0, "arrow", .75, 255, 0, 0, 170 )
    -- attach the marker to the player with a vertical offset of 2 units
    attachElementToElement ( arrowMarker, thePlayer, 0, 0, 2 )
end

-- attach it to an event
addEventHandler ( "onVehicleEnter", vehicleMrWhoopee, onMrWhoopeeEnter )

Example 2: This function adds a tank on top of a player (for extra defense): 

function tankHat( source, commandName )
      local x, y, z = getElementPosition( source ) --Get the players position
      local tank = createVehicle( 432, x, y, z + 5 ) --Create a tank
      attachElementToElement( tank, source, 0, 0, 5 ) --Attach the tank to the player.
end
addCommandHandler( "hat", tankHat )
Click to expand [+]
Client

See Also


Retrieved from "https://wiki.multitheftauto.com/wiki/AttachElementToElement?oldid=44591"