Skip to content

Commit

Permalink
[Update] README.md (move to wiki)
Browse files Browse the repository at this point in the history
  • Loading branch information
@Patrick2562
Patrick2562 committed Feb 7, 2023
1 parent 44d2170 commit 77eb7a1
Show file tree
Hide file tree
Showing 3 changed files with 16 additions and 244 deletions.
248 changes: 5 additions & 243 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,12 @@ Optimized bone attach thanks to the new MTA functions/events.
This resource doesn't match with well known bone_attach, you can not use the same parameters!


# Documnentation
You can find the documentation on Wiki page. [(click here)](https://github.com/Patrick2562/mtasa-pAttach/wiki)


# Performance Comparison
\- There is not so much similiar resources but I will run some performance tests on them.
\- There are not so much similiar resources but I will run some performance tests on them.
CPU usages (Ryzen 5 2600), streamed-in/out attached objects to a ped, on default MTA server with play gamemode.

| Objects count | pAttach (in_stream) | pAttach (out_of_stream) | attachToBones (in_stream) | attachToBones (out_of_stream) | bone_attach (in_stream) | bone_attach (out_of_stream) |
Expand All @@ -16,213 +20,6 @@ CPU usages (Ryzen 5 2600), streamed-in/out attached objects to a ped, on default
| 1000 objects | 46.34% | - | 61.62% | 2.60% | 113.12% | 3.11% |


# Exported Functions (shared)

## **attach**
\- This function attaches an element to the bone of the ped or player.

```
bool attach(element Element, element Ped, int/string Bone [, float xPosOffset = 0, float yPosOffset = 0, float zPosOffset = 0, float xRotOffset = 0, float yRotOffset = 0, float zRotOffset = 0])
```

| Required arguments | Description |
| :----------------- | :------------------------------------------------------------------------------------------------------------ |
| **Element** | The element which you want to attach. (Except: player) |
| **Ped** | The ped or player which you want to attach element to. |
| **Bone** | The number (or name what you can find below) of the ped or player's bone which you want to attach element to. |

| Optional arguments | Description |
| :----------------- | :--------------------- |
| **xPosOffset** | The X position offset. |
| **yPosOffset** | The Y position offset. |
| **zPosOffset** | The Z position offset. |
| **xRotOffset** | The X rotation offset. |
| **yRotOffset** | The Y rotation offset. |
| **zRotOffset** | The Z rotation offset. |

**Returns:** Returns true if element was successfully attached, false otherwise. (only on client side)

## **detach**
\- This function detaches an element from the bone of the ped or player.

```
bool detach(element Element)
```

| Required arguments | Description |
| :----------------- | :-------------------------------------- |
| **Element** | The element which you want to detached. |

**Returns:** Returns true if element was successfully detached, false otherwise. (only on client side)


## **detachAll**
\- This function detaches every elements from the bone of the ped or player.

```
bool detachAll(element Ped)
```

| Required arguments | Description |
| :----------------- | :---------------------------------------------------------------- |
| **Ped** | The ped or player from where you want to detaches every elements. |

**Returns:** Returns true if elements was successfully detached, false otherwise. (only on client side)


## **setPositionOffset**
\- This function changes position offset of attached element.

```
bool setPositionOffset(element Element [, float xPosOffset = 0, float yPosOffset = 0, float zPosOffset = 0 ])
```

| Required arguments | Description |
| :----------------- | :------------------------------------------ |
| **Element** | Element which you want to change offset of. |

| Optional arguments | Description |
| :----------------- | :------------ |
| **xPosOffset** | New X offset. |
| **yPosOffset** | New Y offset. |
| **zPosOffset** | New Z offset. |

**Returns:** Returns true if offset was successfully changed, false otherwise. (only on client side)


## **setRotationOffset**
\- This function changes rotation offset of attached element.

```
bool setRotationOffset(element Element [, float xRotOffset = 0, float yRotOffset = 0, float zRotOffset = 0 ])
```

| Required arguments | Description |
| :----------------- | :------------------------------------------ |
| **Element** | Element which you want to change offset of. |

| Optional arguments | Description |
| :----------------- | :------------ |
| **xRotOffset** | New X offset. |
| **yRotOffset** | New Y offset. |
| **zRotOffset** | New Z offset. |

**Returns:** Returns true if offset was successfully changed, false otherwise. (only on client side)


## **invisibleAll**
\- This function make visible or invisible every attached elements on ped or player.

```
bool invisibleAll(element Element, bool State)
```

| Required arguments | Description |
| :----------------- | :------------------------------------------------------ |
| **Element** | Element which you want to make visible or invisible. |
| **State** | Visibility status. (true = invisible / false = visible) |

**Returns:** Returns true if visibility was successfully changed, false otherwise.


## **isAttached**
\- This function check is element already attached or not.

```
bool isAttached(element Element)
```

| Required arguments | Description |
| :----------------- | :------------------------------- |
| **Element** | Element which you want to check. |

**Returns:** Returns true if element is already attached, false otherwise.


## **setDetails**
\- This function set details of attached element.

```
bool setDetails(element Element [, element Ped = currentPed, int/string Bone = currentBone, float xPosOffset = currentXPosOffset, float yPosOffset = currentYPosOffset, float zPosOffset = currentZPosOffset, float xRotOffset = currentXRotOffset, float yRotOffset = currentYRotOffset, float zRotOffset = currentZRotOffset])
```

| Required arguments | Description |
| :----------------- | :------------------------------------------------------------------------------------------------------------ |
| **Element** | The element which you want to update. |

*NOTE: Use 'false' if you don't want to modify the current value.*
| Optional arguments | Description |
| :----------------- | :------------------------------------------------------------------------------------------------------------ |
| **Ped** | New ped or player which you want to attach element to. |
| **Bone** | New number (or name what you can find below) of the ped or player's bone which you want to attach element to. |
| **xPosOffset** | New X position offset. |
| **yPosOffset** | New Y position offset. |
| **zPosOffset** | New Z position offset. |
| **xRotOffset** | New X rotation offset. |
| **yRotOffset** | New Y rotation offset. |
| **zRotOffset** | New Z rotation offset. |

**Returns:** Returns true if details was successfully changed, false otherwise. (only on client side)


## **getDetails**
\- This function gets details of attached element.

```
table getDetails(element Element)
```

| Required arguments | Description |
| :----------------- | :------------------------------- |
| **Element** | Element which you want to check. |

**Returns:** Returns table with details (value order same as attach function's parameters, starts from Ped) if element exists and attached, false otherwise.


## **setPed**
\- This function set ped or player which you want to attach element to.

```
bool setPed(element Element, element Ped)
```

| Required arguments | Description |
| :----------------- | :----------------------------------------------------- |
| **Element** | Element which you want to update. |
| **Ped** | The ped or player which you want to attach element to. |

**Returns:** Returns true if ped was successfully changed, false otherwise. (only on client side)


## **setBone**
\- This function set bone which you want to attach element to.

```
bool setBone(element Element, int/string Bone)
```

| Required arguments | Description |
| :----------------- | :------------------------------------------------------------------------------------------------------------ |
| **Element** | Element which you want to update. |
| **Bone** | The number (or name what you can find below) of the ped or player's bone which you want to attach element to. |

**Returns:** Returns true if bone was successfully changed, false otherwise. (only on client side)


## **getAttacheds**
\- This function get attached elements which is attached to ped or player.

```
table getAttacheds(element Ped)
```

| Required arguments | Description |
| :----------------- | :---------------------------------------------------- |
| **Ped** | The ped or player to which the elements are attached. |

**Returns:** Returns a table of all the elements attached to the specified ped or player, false otherwise.


# How to use
\- Server sided example to attach objects (parachute, weapon, hat) to player.

Expand All @@ -247,38 +44,3 @@ end)

# Known issues
\- There are desynchronization problems when attaching a player to ped or player.


# Bone IDs and Names
\- You can use the default bone IDs, or the bone-names which makes it easier to use.

| Bone ID | Bone Name | Description |
| :-----: | :--------------------------- | :---------------------------------------------------------------------------------------------- |
| **1** | **pelvis** | Pelvis |
| **2** | **pelvis2** | Pelvis 2 |
| **3** | **spine (OR: backpack)** | Spine |
| **4** | **neck** | Neck (upper torso) |
| **5** | **neck2** | Neck 2 |
| **6** | **head2** | Head 2 |
| **7** | **head3** | Head 3 |
| **8** | **head** | Head |
| **21** | **right-upper-torso** | Right upper torso |
| **22** | **right-shoulder** | Right shoulder |
| **23** | **right-elbow** | Right elbow |
| **24** | **right-wrist (OR: weapon)** | Right wrist |
| **25** | **right-hand** | Right hand (Note: use **right-wrist** instead if you want to attach something to player's hand) |
| **26** | **right-thumb** | Right thumb |
| **31** | **left-upper-torso** | Left upper torso |
| **32** | **left-shoulder** | Left shoulder |
| **33** | **left-elbow** | Left elbow |
| **34** | **left-wrist** | Left wrist |
| **35** | **left-hand** | Left hand (Note: use **left-wrist** instead if you want to attach something to player's hand) |
| **36** | **left-thumb** | Left thumb |
| **41** | **left-hip** | Left hip |
| **42** | **left-knee** | Left knee |
| **43** | **left-tankle** | Left tangle |
| **44** | **left-foot** | Left foot |
| **51** | **right-hip** | Right hip |
| **52** | **right-knee** | Right knee |
| **53** | **right-tankle** | Right tankle |
| **54** | **right-foot** | Right foot |
10 changes: 10 additions & 0 deletions exports.lua
View file
Original file line number Diff line number Diff line change
Expand Up @@ -89,18 +89,21 @@ else

function attach(element, ped, boneid, ox, oy, oz, rx, ry, rz)
assert(isElement(element), "Expected element at argument 1, got "..type(element))

cache[element] = { element, ped, boneid, ox or 0, oy or 0, oz or 0, rx or 0, ry or 0, rz or 0 }
return triggerClientEvent("pAttach:attach", resourceRoot, element, ped, boneid, ox, oy, oz, rx, ry, rz)
end

function detach(element)
assert(isElement(element), "Expected element at argument 1, got "..type(element))

cache[element] = nil
return triggerClientEvent("pAttach:detach", resourceRoot, element)
end

function detachAll(ped)
assert(isElement(ped), "Expected element at argument 1, got "..type(ped))

for element, data in pairs(cache) do
if data[2] == ped then
cache[element] = nil
Expand All @@ -111,6 +114,7 @@ else

function setPositionOffset(element, x, y, z)
assert(isElement(element), "Expected element at argument 1, got "..type(element))

cache[element][4] = x or 0
cache[element][5] = y or 0
cache[element][6] = z or 0
Expand All @@ -119,6 +123,7 @@ else

function setRotationOffset(element, x, y, z)
assert(isElement(element), "Expected element at argument 1, got "..type(element))

cache[element][7] = x or 0
cache[element][8] = y or 0
cache[element][9] = z or 0
Expand Down Expand Up @@ -167,6 +172,7 @@ else

function isAttached(element)
assert(isElement(element), "Expected element at argument 1, got "..type(element))

return cache[element] and true or false
end

Expand All @@ -187,13 +193,15 @@ else

function getDetails(element)
assert(isElement(element), "Expected element at argument 1, got "..type(element))

return cache[element] or false
end

function getAttacheds(ped)
assert(isElement(ped), "Expected element at argument 1, got "..type(element))

local list = {}

for element, data in pairs(cache) do
if data[2] == ped then
list[ #list + 1 ] = element
Expand All @@ -204,6 +212,7 @@ else

addEventHandler("onPlayerResourceStart", root, function(res)
if res ~= resource then return end

triggerClientEvent(source, "pAttach:receiveCache", resourceRoot, cache)
end)

Expand All @@ -214,6 +223,7 @@ else
addEventHandler("onElementDestroy", root, function()
if cache[source] then
detach(source)

elseif getElementType(source) == "ped" then
for element, data in pairs(cache) do
if data[2] == source then
Expand Down
2 changes: 1 addition & 1 deletion meta.xml
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<meta>
<info author="!Patrick" name="pAttach" type="script" version="1.2.0"/>
<info author="!Patrick" name="pAttach" type="script" version="1.2.1"/>
<min_mta_version server="1.5.8-9.20957" client="1.5.8-9.20837" />
<oop>true</oop>

Expand Down

0 comments on commit 77eb7a1

Please sign in to comment.