~~NOTOC~~
<=[[4rpl:start| Index]]  \\
<=[[4rpl:start#beams| Beams]]


====== AttachBeam ======
AttachBeam(<-beamUID <-unit <-objName)

===== Description =====
Attaches a beam to a unit's object. When a beam is attached to a object, the beam's start position becomes relative to the object. Note that "" is the root object of a unit.
This allows the beam start to follow the unit around if the unit moves.  The end position remains in world coordinates, unless SetBeamForceLocalEnd is called on the beam.
The beam can only be attached to one unit at a time.  If you attach a beam to a new unit while it is already attached to some other unit, the beam will unattach from the old unit then attach to the new unit.

**Important note:** If you are planning to create a continuous beam on a unit that will be moving while firing, do not attach the beam to the unit. An attached beam will be unable to maintain the correct visual orientation and length. An unattached beam so long as its' start location is updated will retain a correct visual orientation.
===== Examples =====
<code 4rpl>
once
   GetUnitPosition(self) ->unitPos
   #Fire a beam to extends off screen but is at the same height as the unit
   #We will attach the beam to ourselves, so that the start point is relative to our unit
   3 ->brightness
   4 ->width
   CreateBeam("orange" <-brightness <-width) ->beam
   AttachBeam(<-beam self "")
   SetBeamStart(<-beam V3(0 0 0))
   SetBeamEnd(<-beam V3(10000 0 10000))
endonce
</code>
<=[[4rpl:start| Index]]