LSL Wiki : energy

Energy

An object's energy, as reported by llGetEnergy, is quite distinct from the RL physics definition of energy. SL energy is actually a throttle on how effectively scripts can change the motion of physical objects. The energy of an object ranges from 0.0 to 1.0. If an object's energy is 1.0, LSL functions that attempt to change the object's motion will have their full effect. If the energy of the object is 0, the same functions will have no effect. Intermediate energy values give intermediate effects.

An object gains energy through a stipend, which it earns merely by existing in the rezzed state. An object expends energy when scripts call functions to change its motion. SL's energy was implemented to limit the amount scripts can use certain dynamics functions.

Each time an object is rezzed, or its mass is changed (like by changing its size or shape), its energy is reset to 0.

Earning Energy

While rezzed, an object is credited with energy at a rate that is determined by its mass. The more massive the object is, the slower it earns energy. Specifically, the energy stipend is 200/mass units of energy per second. When an object's energy reaches 1.0, the stipend is suspended until the energy falls below 1.0. Thus, an object with mass close to 1 (like a simple avatar) will return to full energy instantly; an object with a mass of 100 will be full in half a second; an object with a mass of 2000 will be topped off in 10 seconds; et cetera.

Expending Energy

The following functions immediately reduce the amount of energy of the object running the script:

llApplyImpulse llApplyRotationalImpulse llPushObject

For the first two, the amount of energy expended is the magnitude of the impulse vector divided by 20,000. For llPushObject, it is the sum of the expenditures due to the two impulse vectors. Note: for llPushObject, the object being pushed does not lose energy.

These functions also reduces the amount of energy of the object being affected:

llMoveToTarget llRotLookAt llLookAt llSetForce llSetTorque llSetForceAndTorque llSetHoverHeight llGroundRepel llSetBuoyancy

The amount of energy used by calls to these functions is affected by the mass of the object in question. The different functions also seem to have varying levels of efficiency. Some tasks take more energy for a given mass than others. Persistent functions like llSetBuoyancy and llMoveToTarget constantly use energy and will not function if the mass of the object is above a limit determined by the rate of recharge vs. the efficiency of the function. Smaller objects (those with lesser mass) gain energy quicker.

The energy an object has can be determined by calling llGetEnergy.

Q: Is it by object or by prim?
A: The root prim has the combined energy of all the child prims and its own, as it does with mass. Scripts in child prims will reflect the energy of that prim, same with mass.

A lot isn't known about energy. If anyone has performed tests, please don't hesitate to post more information here.

I've done some experimenting, and energy has far greater effects on scripts. First off, energy potential is based off mass. If the prim has negative mass (LSL mass functions are kind of screwy) then scripts will not run; events won't register (but they will still be shown like for money & touch). If you try and pay an object with negative mass you will get an "out of energy" error box. But, fortunately, there is a workaround for negative-mass prims: make the bad prim the root prim and link in another prim to balance it out. I've concluded the reason scripts don't run (Lindens wouldn't spill the beans when I asked; they told me it was kind of like magic), is that negative-mass prims totally foul up the center-of-mass calculations in LSL and, more importantly, totally do a number on vehicles (I think vehicles are implemented through LSL more then Havok). With some very screwed up prims (don't ask) you can have prims on the other side of the mass equations. The interesting thing is that, under certain circumstances, a prim can be made to shift from positive mass to negative mass and vice versa by manipulating the twist, hollow, top size & top shear. Most interesting is the fact that some combinations of attributes on normally negative-mass prims result in super positive-mass prims. Haven't thought of a good use for them.

On a side note, center-of-mass & mass is used for link distances, not prim size. My findings with prim mass has lead me to conclude that LSL & Havok's mass calculations are done separately (negative-mass objects don't fly into the sky as expected). Will post more when I do the experiments; at the moment I'm trying to keep off LL radar, but I guess I just failed at doing that. :p

SL 1.5 has different rules with mass, and scripts now run in objects that once had negative mass. To read more on this topic read the notes on llSetPrimitiveParams -BW

Functions | Mass | Dynamics | Physics

The time it takes for a prim to regen from 0 Energy to 1 is llGetMass()/200;
Test: place this snippet in to a very large prim, then take and rez it. Compare mass and time to full.

50 seconds for a prim with a mass of 10,000

on_rez(integer param)
{
llResetTime()
while(llGetEnergy() < 1) llSleep(0.001);
llOwnerSay((string)llGetTime());
}

The effect of energy on a llPushObject is expressed by multiplying the current energy by the requested push vector.
so if you requested a push of <0,0,10> and your current energy is 0.5 then you would end up with a push applied of <0,0,5>

Test: Take a very large prim, and reduce its energy to 0, llSleep() for whatever percentage of Time-To-Full you want i.e.
llSleep( (llGetMass()/200)*0.5) for half energy, adjust time for code script execution time for accuracy.
Then apply a push that you know the expected result of, and it will be halved. if you set the delay to 1/10 time to full the effect will be 1/10 normal. The easiest way to test push effect is set a prim to neutral buoyancy and test velocity before and after push.

Compensating for energy, while possible, is impractical for most situations, due to the rapid rate of energy regeneration in small objects, and the highly variable speed LSL scripts execute at. Easier to just know the time it takes your pusher to refill, and only apply pushes at higher intervals than that.

This is not really an energy issue, its more of an llPushObject issue, but it can destroy your attempts to experiment if you don’t take it in to account.

llPushObject has an particular range, beneath which it operates differently, specifically the calculations for the pushing prims mass, and energy behave differently. The farther inside this range you are, the less effect the mass of the prim containing the push script has, and the less energy you need to achieve full effect.

This radius varies depending on the mass of the pushing prim. my best guess at calculating it is llPow(llGetMass()/10,1.0/3.0) the fall off of the effect of the pushing prims mass as you move inside this radius is cubic, I haven’t checked yet how the fall off on required energy is calculated.

-- KrashnburnHillquit (2006-03-23 08:09:18)