View source for LUPS


Lua Particle System (LUPS)

Licensed under the terms of the GNU GPL, v2 or later.

== github ==
https://github.com/jk3064/lups

== Download ==

Lups is available via [[rapid]] and can be downloaded via the usual tags, i.e. lups:stable.


== Implementation ==
First, you need to differ between synced and unsynced FX,
so there are 2 LUPS instances running:
one in LuaUI (widget) and
one in LuaRules (gadget).
(To start a new instance simply include lups/lups.lua)



== Why differ between synced and unsynced FX? ==
LuaUI has only a limited access to engine values, so it
could never determine the unittype of enemy units in airlos,
nor is it able to catch weapon explosion or to interact with
cob.



== Which files are used by LUPS? ==
the core uses the following:
lups/*
bitmaps/GPL/lups/*
LuaUI/Widgets/lups_wrapper.lua
LuaRules/Gadgets/lups_wrapper.lua (only if you want synced
FX like shockwaves/nanolasers)
and there are the managers:
LuaUI/Widgets/gfx_lups_manager.lua
LuaRules/Gadgets/gfx_lups_manager.lua
the shockwaves gadget:
LuaRules/Gadgets/lups_shockwaves.lua



== What are those managers? ==
LUPS itself doesn't start any FX. It needs other lua files
to tell LUPS when it should start a new FX.
There are many widgets and gadgets, which start LUPS FXs,
but the most interesting ones are the managers (and perhaps
the shockwaves gadget).
Also the manager in LuaRules differ from that one in LuaUI.
The manager in LuaUI starts FXs everytime an new unit gets
finished or an enemy unit enters the LOS, so those FX only
vanish if the unit dies or leaves the LOS again.
The LuaRules manager is much less customizable, it creates
very special FXs like cloaking and it also manage parts of
the LUPS nano particle handling.



== How do I implement my own FX? ==
Okay, in the case you use the LuaUI manager and you want to
create a per-unit FX (like a fusion FX, airjets, ...):

1. open LuaUI/Widgets/gfx_lups_manager.lua
(don't shock the file seems huge, but most is only config,
and yeah it needs a cleanup ... someday :x)
2. scroll down (~50% scrollbar)
you will find the following table/array:
"local UnitEffects = {...}"
It holds the FX per-unitdef.
3. create a new sub-table like the following:
[UnitDefNames["%UNITDEF_NAME%"].id] = {
{class='%FXCLASS%',options=%MY_FXOPTIONS_TABLE%}
},



== What FXClasses exist and how do I know their options? ==
All FXClasses are located here:
/lups/ParticleClasses/*
If you open on of those files, you will see a function like this:

function ShieldSphereParticle.GetInfo()
return {
name      = "ShieldSphere",
}
end

That returned name is what you fill in %FXCLASS% (uppercase
doesn't matter), also it is in most cases same as the filename.
To see possible options of the FXClass scroll a bit down, you
will find a table like this:

ShieldSphereParticle.Default = {
pos        = {0,0,0}, -- start pos
layer      = -23,
life       = 0, --in frames
size       = 0,
sizeGrowth = 0,
margin     = 1,
colormap1  = { {0, 0, 0, 0} },
colormap2  = { {0, 0, 0, 0} },
repeatEffect = false,
}

The table contains all options and their default values.
So an example fx placed in LuaUI/Widgets/gfx_lups_manager.lua
could look like this:
[UnitDefNames["armcom"].id] = {
{class='ShieldSphere',options={ life=3000, repeatEffect=true, size=300, colormap1={1,0,0,0.5}, colormap2={0,1,0,0.5} } }
},



== How do I start my own FX from my widget/gadget? ==
First, you need a link to the interface, to do so you need
to access the global shared table of the widget-/gadgetHandler.
for LuaUI:
local LupsApi = WG.Lups
for LuaRules:
local LupsApi = GG.Lups
(nil check those, it is possible that Lups hasn't started yet!)

That Api contains the following functions:
LupsApi.GetStats()
LupsApi.GetErrorLog(minPriority)
->  LupsApi.AddParticles(class,options)   //returns a fxID
->  LupsApi.RemoveParticles(fxID)
LupsApi.AddParticlesArray({ {class=className, ..FX options..},{class=className, ..FX options..},.. } )
LupsApi.HasParticleClass(className)
and
LupsApi.Config = {...}  //contains the options of lups.cfg



== Example usage of AddParticles() ==
LupsApi.AddParticles('ShieldSphere', {
unit=unitID,
piece="head",
pos={0,100,0},
life=3000,
repeatEffect=true,
size=300,
colormap1={1,0,0,0.5},
colormap2={0,1,0,0.5}
})



== How do I bind a FX to an unit/unitpiece? ==
There are some special options tags, those are:
unit := binds fx to unitID
piece:= binds fx to pieceNAME
pos  := worldspace coord or offset coord from the unit/unitpiece center
onActive := only show FX if the unit is active (e.g. used for airjets - a plane is active, if it flies)



== Can I modify FX on runtime? ==
Sure you can. There is only one issue in 76b1 (it will
be fixed in the next spring release):
you can't modify widgets if they are in a .sdd, so you
have to copy it to your local widgets folder,
then you can run:
/luaui reload
each time you modified the file.



== I heard some options can contain Lua code? ==
Yeah, but only the SimpleParticles class support them and
_only_ in the "partpos" param:

LupsApi.AddParticles('SimpleParticles', {
...
partpos = "r*cos(beta)*sin(alpha),r*cos(alpha),r*sin(beta)*sin(alpha) | r=random()*20, alpha=2*math.pi*random(), beta=2*math.pi*random()"
...
})

The syntax is a bit extended so it looks similar to the
definitions of a mathical sets, but it can still contain
any lua code.

Valid examples are:
"x,y,z | x=10,y=30,z=0"
"10,30,0"
"random(),random(),random()"
"x,y,z | r=random(), if (r>10) then x=10; y=30; z=0; else x=-10; y=-30; z=-0; end"

[[Category:Libraries]]