CreateBeam(<-color <-brightness <-width) ->beamUID

Creates a beam. Beams are laser like lines between two points in 3D space. A beam will persist once created. Call DestroyBeam to remove a beam. Don't call CreatBeam repeatedly unless you plan to make more than one beam. Each call creates a new beam that will persist until destroyed. If you are creating a beam for a unit, call CreateBeam in a once clause (or some other initialization function) then reference that beam in the unit. You can toggle the beam's visibility rather than creating, destroying, and recreating the beam. Toggling the visibility is more efficient that creating and destroying a beam. If you attach a beam to a unit, the beam will be destroyed if the unit is destroyed. CreateBeam pushes to the stack a unique ID for the created beam. Use this ID in other beam related calls to reference the beam. A value of -1 is pushed to the stack if the beam creation fails. A MAXIMUM OF 4096 BEAMS IS ALLOWED.

• 'Color' is a string. Possible values are “black”, “red”, “orange”, “yellow”, “green”, “blue”, “purple”, “white”.
• 'brightness' is a float ranging from 0 to 10. A value of 0 makes the beam totally black. A value of 1 is fully colored. Values above 1 increase the brightness into the HDR glow range.
• 'width' is a float ranging from 0 up. The width is the thickness of the beam. Beams are flat geometry so keep the beam width relatively small (1-10 typically).

Important note: If you are planning to create a continuous beam on a unit that will be moving while firing or the end of the beam is meant to track something that moves, do not attach the beam to the unit. An attached beam will be unable to maintain the correct visual orientation and length in such situations. An unattached beam so long as its' start and end location is updated will retain a correct and accurate visual orientation and will give much better results.
Attached beams are best for simple units such as a unit that fires a beam at Creeper. The targeted Creeper location does not move and if the unit does not move while the beam is visible than it is safe to attach the beam to the unit and no unwanted visual errors will occur.

Beams become very difficult to see from long distances when they are a size lower than 0.35 so if you want the beam to always be visible, keep the width at a minimum of 0.35.
This can also be useful when using a large number of beams such as targeting lasers for decorating purposes rather than functional purposes to ensure the player's screen is not flooded with beams when zoomed out when using many of that unit.

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

⇐ Index