Element functions

Author: FileEX

assets/images/rotation_ypr.webp

@@ -1,11 +1,6 @@
-# Scraped from: https://wiki.multitheftauto.com/wiki/AddElementDataSubscriber
-shared:
+server:
   name: addElementDataSubscriber
-  description: 'This function subscribes a [player](/wiki/Player "Player") to specific
-    [element data](/wiki/Element_data "Element data").
-
-    This function is used together with [setElementData](/wiki/SetElementData "SetElementData")
-    in *"subscribe"* mode.'
+  description: This function subscribes a [[player]] to specific [element data](/reference/Element_data). This function is used together with [[setElementData]] in `"subscribe"` mode.
   parameters:
   - name: theElement
     type: element
@@ -18,23 +13,22 @@ shared:
     description: The player you wish to subscribe.
   examples:
   - path: examples/addElementDataSubscriber-1.lua
-    description: ''
-    side: server
+  - path: examples/addElementDataSubscriber_OOP-1.lua
+    oop: true
   returns:
     values:
     - type: bool
-      name: value
-    description: Returns true if the player was subscribed, false otherwise.
+      name: result
+    description: Returns **true** if the player was subscribed, **false** otherwise.
   oop:
     element: element
     method: addDataSubscriber
     static: false
   pair: removeElementDataSubscriber
   notes:
   - type: info
-    content: Before using this function you need to setup an initial value of element
-      data in "subscribe" mode, otherwise the subscriber will not be added.
-  - type: info
-    content: Calling removeElementData or setElementData with other sync mode will
-      automatically remove all subscribers of specified element data.
-  requires_review: true
+    content: |
+      - Before using this function you need to setup an initial value of element
+        data in `"subscribe"` mode, otherwise the subscriber will not be added.
+      - Calling [[removeElementData]] or [[setElementData]] with other sync mode will
+        automatically remove all subscribers of specified element data.

assets/images/setElementAlpha.png

@@ -1,8 +1,6 @@
-# Scraped from: https://wiki.multitheftauto.com/wiki/AttachElements
-shared:
+shared: &shared
   name: attachElements
-  description: This function attaches one element to another, so that the first one
-    follows the second whenever it moves.
+  description: This function attaches one [[element]] to another, so that the first one follows the second whenever it moves.
   parameters:
   - name: theElement
     type: element
@@ -12,54 +10,68 @@ shared:
     description: The element to attach the first to.
   - name: xPosOffset
     type: float
-    description: The x offset, if you want the elements to be a certain distance from
-      one another (default 0).
+    description: The X offset, if you want the elements to be a certain distance from
+      one another.
     default: '0'
   - name: "yPosOffset"
     type: float
-    description: The y offset (default 0).
+    description: The Y offset.
     default: '0'
   - name: zPosOffset
     type: float
-    description: The z offset (default 0).
+    description: The Z offset.
     default: '0'
   - name: xRotOffset
     type: float
-    description: The x rotation offset (default 0).
+    description: The X rotation offset.
     default: '0'
   - name: "yRotOffset"
     type: float
-    description: The y rotation offset (default 0).
+    description: The Y rotation offset.
     default: '0'
   - name: zRotOffset
     type: float
-    description: The z rotation offset (default 0).
+    description: The Z rotation offset.
     default: '0'
-  examples:
-  - path: examples/attachElements-1.lua
-    description: 'Example 1:This example attaches a marker to the player who steals
-      the Mr. Whoopee:'
-    side: server
-  - path: examples/attachElements-2.lua
-    description: 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.
-    side: client
   returns:
     values:
     - type: bool
-      name: value
-    description: Returns true if the attaching process was successful, false otherwise.
+      name: result
+    description: Returns **true** if the attaching process was successful, **false** otherwise.
   oop:
     element: element
     method: attach
+    variable: attachedTo
+    note: The variable can only be used if the offsets can be 0 (use [setElementAttachedOffsets](/reference/setElementAttachedOffsets)).
     static: false
   pair: detachElements
   notes:
   - type: info
-    content: The offset coodinates reflect the object space, not the world space.
+    content: |
+      - The offset coodinates reflect the object space, not the world space.
       This means that you cannot calculate the exact offsets between two objects by
-      pre-positioning them in the map editor as a reference. Please see attachElementsOffsets
-      for more details. Due to a limitation in GTA, unexpected attach rotations may
+      pre-positioning them in the map editor as a reference. Please see [[attachElementsOffsets]]
+      for more details.
+      - Due to a limitation in GTA, unexpected attach rotations may
       occur if all rotation offsets are non-zero. (i.e. Try to ensure at least one
-      of 'xRotOffset', 'yRotOffset' or 'zRotOffset' is zero).
-  requires_review: true
+      of `xRotOffset`, `yRotOffset` or `zRotOffset` is zero).
+      - 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: [[ped]], [[player]], [[blip]], [[vehicle]], [[object]], [[marker]], [[pickup]], [[sound]], [[colshape]], [[weapon]], [[camera]], [[light]].
+server:
+  <<: *shared
+  examples:
+  - path: examples/attachElements-1.lua
+    description: 'This example attaches a marker to the player who steals the Mr. Whoopee.'
+  - path: examples/attachElements-2.lua
+    description: This function adds a tank on top of a player (for extra defense).
+  - path: examples/attachElements_OOP-1.lua
+    description: This function adds a tank on top of a player (for extra defense).
+    oop: true
+
+client:
+  <<: *shared
+  examples:
+    - path: 'examples/attachElements-3.lua'
+      description: This function adds a tank on top of a player (for extra defense), clientside. This means it will be invisible to other players.
+    - path: examples/attachElements_OOP-2.lua
+      oop: true

assets/images/setElementBonePosition.png

@@ -1,25 +1,23 @@
-# Scraped from: https://wiki.multitheftauto.com/wiki/ClearElementVisibleTo
-shared:
+server:
   name: clearElementVisibleTo
-  description: This function clears any settings added by [setElementVisibleTo](/wiki/SetElementVisibleTo
-    "SetElementVisibleTo") and restores an [element](/wiki/Element "Element") to its
-    default [visibility](/wiki/Visibility "Visibility").
+  pair: setElementVisibleTo
+  description: This function clears any settings added by [[setElementVisibleTo]] and restores an element to its default [[Visibility]].
   parameters:
   - name: theElement
     type: element
-    description: The element in which you wish to restore to its default visibility
+    description: The element in which you wish to restore to its default visibility.
   examples:
   - path: examples/clearElementVisibleTo-1.lua
-    description: This example clears any visibility settings after a player dies,
-      so everyone can see his blip for a short period
-    side: server
+    description: This example clears any visibility settings after a player dies, so everyone can see his blip for a short period.
+  - path: examples/clearElementVisibleTo_OOP-1.lua
+    description: This example clears any visibility settings after a player dies, so everyone can see his blip for a short period.
+    oop: true
   returns:
     values:
     - type: bool
-      name: value
-    description: Returns true if the operation was successful, false otherwise.
+      name: result
+    description: Returns **true** if the operation was successful, **false** otherwise.
   oop:
     element: element
     method: clearVisibility
-    static: false
-  requires_review: true
+    static: false

assets/images/setElementBoneQuaternion.png

@@ -1,10 +1,7 @@
-# Scraped from: https://wiki.multitheftauto.com/wiki/CloneElement
-shared:
+server:
   name: cloneElement
   description: This function clones (creates an exact copy of) an already existing
-    element. The root node, and player elements, cannot be cloned. If a player element
-    is a child of an element that is cloned, it will be skipped, along with the elements
-    that exist as a child to the player element.
+    element.
   parameters:
   - name: theElement
     type: element
@@ -28,17 +25,25 @@ shared:
     default: 'false'
   examples:
   - path: examples/cloneElement-1.lua
-    description: This example clones the vehicle a player is in.  This allows carrying
+    description: This example clones the vehicle a player is in. This allows carrying
       over of the current state of the vehicle, including mods, for example.
-    side: server
+  - path: examples/cloneElement_OOP-1.lua
+    description: This example clones the vehicle a player is in. This allows carrying
+      over of the current state of the vehicle, including mods, for example.
+    oop: true
   returns:
     values:
     - type: element
-      name: value
-    description: Returns the handle of the new cloned element of the parent, false
+      name: cloned element
+    description: Returns the handle of the new cloned element of the parent, **false**
       if invalid arguments were passed.
   oop:
-    element: element
+    element: element|false
     method: clone
     static: false
-  requires_review: true
+  notes:
+    - type: info
+      content: |
+        - if `cloneChildren` is **true**, the position floats will be offsets from the cloned element's position.
+        - The root node, and player elements, cannot be cloned. If a player element is a child of an element that is cloned, it will be skipped, along with the elements that exist as a child to the player element. Players are not the only elements that cannot be cloned. This list also includes remoteclients, and console elements.
+        - The cloned element will be placed on the [element tree](/reference/Element_tree) as a child of the same parent as the cloned element.

functions/Element/addElementDataSubscriber.yaml

@@ -1,10 +1,9 @@
-# Scraped from: https://wiki.multitheftauto.com/wiki/CreateElement
 shared:
   name: createElement
-  description: This function is used to create a new dummy element in the [element
-    tree](/wiki/Element_tree "Element tree") which do not necessarily represent an
+  pair: destroyElement
+  description: This function is used to create a new dummy [[element]] in the [element tree](/reference/Element_tree) which do not necessarily represent an
     entity within the San Andreas world. A common use for this function is for creating
-    custom elements, such as a Flag or a Base.
+    custom elements, such as a **Flag** or a **Base**.
   parameters:
   - name: elementType
     type: string
@@ -15,20 +14,32 @@ shared:
     default: nil
   examples:
   - path: examples/createElement-1.lua
-    description: This example creates a "flag" element, named "blue", which will be
-      at the resource's dynamic map.
-    side: server
-  - path: examples/createElement-2.lua
-    description: 'Except for it being placed in a different map root, that line will
-      have the same effect as having this in a .map file:'
-    side: server
+    description: |
+      This example creates a "flag" element, named "blue", which will be at the resource's dynamic map.
+
+      Except for it being placed in a different map root, that line will have the same effect as having this in a .map file:
+      ```xml
+        <flag id="blue" />
+      ````
+
+      Lua
+  - path: examples/createElement_OOP-1.lua
+    description: |
+      This example creates a "flag" element, named "blue", which will be at the resource's dynamic map.
+
+      Except for it being placed in a different map root, that line will have the same effect as having this in a .map file:
+      ```xml
+        <flag id="blue" />
+      ````
+
+      Lua
+    oop: true
   returns:
     values:
-    - type: element
-      name: value
-    description: Returns the element if it was successfully created. Returns false
+    - type: element|false
+      name: created element
+    description: Returns the [[element]] if it was successfully created. Returns **false**
       if the arguments are wrong.
   oop:
     element: element
-    constructorclass: Element
-  requires_review: true
+    constructorclass: Element

functions/Element/attachElements.yaml

@@ -1,11 +1,11 @@
-# Scraped from: https://wiki.multitheftauto.com/wiki/DestroyElement
-shared:
+shared: &shared
   name: destroyElement
-  description: This function destroys an [element](/wiki/Element "Element") and all
+  pair: createElement
+  description: This function destroys an [[element]] and all
     elements within it in the hierarchy (its children, the children of those children
-    etc). [Player](/wiki/Player "Player") elements cannot be destroyed using this
+    etc). [[player]] elements cannot be destroyed using this
     function. A player can only be removed from the hierarchy when they quit or are
-    kicked. The root element also cannot be destroyed, however, passing the root as
+    kicked. The [[root]] element also cannot be destroyed, however, passing the root as
     an argument will wipe all elements from the server, except for the players and
     clients, which will become direct descendants of the root node, and other elements
     that cannot be destroyed, such as resource root elements.
@@ -15,45 +15,44 @@ shared:
     description: The element you wish to destroy.
   examples:
   - path: examples/destroyElement-1.lua
-    description: Example 1:This example would destroy every element in the map, with
-      the exception of players and the root element itself.
-    side: server
+    description: This example would destroy every element in the map, with the exception of players and the root element itself.
   - path: examples/destroyElement-2.lua
-    description: 'Example 2:This example destroys all vehicles of the specified model:'
-    side: server
-  - path: examples/destroyElement-3.lua
-    description: Example 3:This example allows creation of claymores, which trigger
-      and explode.  When they explode, the colshape and object for the claymore are
-      destroyed.
-    side: server
+    description: 'This example destroys all vehicles of the specified model.'
+  - path: examples/destroyElement_OOP-1.lua
+    description: 'This example destroys all vehicles of the specified model.'
+    oop: true
   - path: examples/destroyElement-4.lua
-    description: 'Example 4:This example destroys all vehicles, regardless of ID,
-      name, etc:'
-    side: server
+    description: 'This example destroys all vehicles, regardless of ID, name, etc.'
   returns:
     values:
     - type: bool
-      name: value
-    description: Returns true if the element was destroyed successfully, false if
+      name: result
+    description: Returns **true** if the element was destroyed successfully, **false** if
       either the element passed to it was invalid or it could not be destroyed for
       some other reason (for example, clientside destroyElement can't destroy serverside
       elements).
   oop:
     element: element
     method: destroy
-    static: false
   notes:
+  - type: tip
+    content: There is bug when you try to destroy webbrowser that returned from [[guiGetBrowser]]
+      so instead of that destroy the gui-element one that returned from [[guiCreateBrowser]]
+      otherwise the game will be crushed.
   - type: info
-    content: There is bug when you try to destroy webbrowser that returned from guiGetBrowser
-      so instead of that destroy the gui-element one that returned from guiCreateBrowser
-      otherwise the game will be crushed (By Master_MTA).
-  - type: info
-    content: As element ids are eventually recycled, always make sure you nil variables
-      containing the element after calling this function
-  - type: info
-    content: If a streamed-in element is destroyed then it is NOT streamed out, i.e.
-      the onClientElementStreamOut client-side event is NOT triggered. Thus it is
+    content: |
+      - As element ids are eventually recycled, always make sure you nil variables
+        containing the element after calling this function
+      - If a streamed-in element is destroyed then it is **NOT** streamed out, i.e.
+      the [[onClientElementStreamOut]] client-side event is **NOT** triggered. Thus it is
       wrong to assume a clean stream-in and stream-out sequence on the client-side.
-      Additionally to onClientElementStreamOut use a onClientElementDestroy event
+      Additionally to [[onClientElementStreamOut]] use a [[onClientElementDestroy]] event
       handler to detect the destruction of streamed-in elements.
-  requires_review: true
+
+server:
+  <<: *shared
+  examples:
+  - path: examples/destroyElement-3.lua
+    description: This example allows creation of claymores, which trigger
+      and explode. When they explode, the colshape and object for the claymore are
+      destroyed.