Return to Index

Status

Description:

The status object contains all the information about the player stats, currents effects and ressources such as health and energy







Contains




Documentation

addEphemeralEffect(String effect) : void

Description:

This function will allow you to add an effect to the player for the effect default duration.
If the player already has this effect, it will renew it.

You can set the duration by using the addEphemeralEffects(String effect, float duration)

Parameter(s):

effect :

A string representing the effect you will give to the player.

You can find all the effect names in the /stats/effects folder in the main assets.

Retun:

No Data Returned

Example:

status.addEphemeralEffect("glow");
world.logInfo("your all shiny now!");

addEphemeralEffect(String effect, float duration) : void

Description:

This function will allow you to add an effect to the player for a certain period of time.
If the player already has this effect, it will renew it for the amount of time that was specified.

Parameter(s):

effect :

A string representing the effect you will give to the player.

You can find all the effect names in the /stats/effects folder in the main assets.

duration :

The duration of the effect in seconds. If you want it to stay for a really long time, use math.huge.

Retun:

No Data Returned

Example:

status.addEphemeralEffect("bouncy",math.huge);
world.logInfo("MUHAHAHA YOU WILL BOUNCE FOR THE REST OF YOUR LIFE!");

addEphemeralEffects(table<String effect> effects) : void

Description:

This function will allow you to add multiple effects to the player.
There is no way to set the duration of the effects, therefore they will last their default duration.
If the player already has this effect, it will renew it for the amount of time that was specified.

Parameter(s):

table<String effect> effects :

A table representing the effects you will give to the player.

You can find all the effect names in the /stats/effects folder in the main assets.

duration :

The duration of the effect in seconds. If you want it to stay for a really long time, use math.huge.

Retun:

No Data Returned

Example:

status.addEphemeralEffects({"bouncy","glow"});
world.logInfo("your all bouncy and glowy now!");

addPersistentEffect(String name, String effect OR JSON effect) : void

Description:

This function will add a certain persistent effect that can be refered to by a specific name.

You can use clearPersistentEffects() and clearAllPersistentEffects() functions to remove the persistent effect from the player.

You can also use addPersistentsEffects() to add more than one effect under the same name at once.

If you are adding a permanent effect using an already existing name it will add it this way :

Status effect name as a string
If the effect is already there, it will do nothing, if it isn't it will add it.
Using a JSON object
The stat value you are adding will be added to the total value of the stat.

Parameter(s):

Name :

The name of the permanant effect you will use to refer to it. it has literaly nothing to do with the files of the game, only with how you want to refer to this effect.

Effect :

A string or an JSON object containing a stat modification.

Using a JSON object
elements :
stat: the name of the stat
one of these :
amount :
A set amount will be added.
effectivePercentage :
Adds a percentage of the player's stat.
basePercentage :
Adds to the base value.
Status effect name as a string
If the effect is already there, it will do nothing, if it isn't it will add it.

Retun:

No Data Returned

Example:

-- Using a the name of an effect
 
status.addPersistentEffect("slowDeath","weakpoison");
 

 
-- Using a JSON argument with amount
-- Assuming fallDamageMultiplier has a value of 1 which means 100%
 
status.addPersistentEffect("longFallBoots",{ stat = "fallDamageMultiplayer", amount = -0.5});
-- the player will now recieve half the fall damage since we added -50%.
 

 
-- Using a JSON argument with effectivePercentage
-- Assuming powerMultiplier has a value of 3 which means 300%, the 200% extra are from a piece of armor and the other 100% being the base power
 
status.addPersistentEffect("PowerPunch",{ stat = "powerMultiplier", effectivePercentage = 0.25});
-- the player powerMultiplier will now have a value of 375%
 
status.addPersistentEffect("PowerPunch",{ stat = "powerMultiplier", effectivePercentage = 0.25});
-- the player powerMultiplier will now have a value of 450%
 

 
-- Using a JSON argument with basePercentage
-- Assuming powerMultiplier has a value of 3 which means 300%, the 200% extra are from a piece of armor and the other 100% being the base power.
 
status.addPersistentEffect("weakerPunch",{ stat = "powerMultiplier", basePercentage = -0.25});
-- the player powerMultiplier will now have a value of 275%
 
status.addPersistentEffect("Punch",{ stat = "powerMultiplier", basePercentage = 0.25});
-- the player powerMultiplier will now have a value of 300%

addPersistentEffects(String name, table<JSON effect AND/OR String effect> effects) : void

Description:

This function is the same thing as the addPersistentEffect() function but with multiple effects added at once.

Parameter(s):

Name :

The name of the permanant effect you will use to refer to it. it has literaly nothing to do with the files of the game, only with how you want to refer to this effect.

Effect :

An array containing the effects you want to add. it can contain a mix of Strings and JSON object at the same time.

Using a JSON object
elements :
stat: the name of the stat
one of these :
amount :
A set amount will be added.
effectivePercentage :
Adds a percentage of the player's stat.
basePercentage :
Adds to the base value.
Status effect name as a string
If the effect is already there, it will do nothing, if it isn't it will add it.

Retun:

No Data Returned

Example:

-- Using a the a mix of JSON and Strings
status.addPersistentEffects("crashDummy",{"bouncy",{ stat = "fallDamageMultiplier", amount = -1 }});
 

 
-- Using JSON only
status.addPersistentEffects("theAllMighty",{{ stat = "invisible", amount = 1 },{ stat = "invincible", amount = -1 }});
 

 
-- Using Strings only
status.addPersistentEffects("theFlash",{"runboost", "glow"});
 

 
-- yes you can use a single element
status.addPersistentEffects("aLamp",{"glow"});

clearAllPersistentEffects() : void

Description:

remove all the persiarant effect the player has.
You can remove a specific effect by using the clearPersistentEffects(String) function.

Parameter(s):

No Parameters

Retun:

No Data Returned

Example:

status.clearAllPersistentEffects();
world.logInfo("You feel all of your powers going away");

clearEphemeralEffects() : void

Description:

remove all the ephemerals effect the player has.

You can remove a specific effect by using the removeEphemeralEffect(String) function.

Parameter(s):

No Parameters

Retun:

No Data Returned

Example:

status.addEphemeralEffect("glow");
status.clearEphemeralEffects();
world.logInfo("NOPE! You're not a flashlight!");

clearPresistentEffects(String effect) : void

Description:

Removes all the effects added by a specific persistent effect. It also removes the persistent effect.

You can remove them all, by using clearAllPersistentEffects().

Parameter(s):

effect :

The name of the persistent effect you want to remove.

Retun:

No Data Returned

Example:

status.clearPersistentEffects("I AM PROBABLY AN EFFECT");
world.logInfo("you feel a part of your powers go away.");

consumeResource(String resource, float amount) : bool

Description:

This function will consume a specified amount of a specified resource such as energy or health and returns a value indicating of the player had enough of the specified resource.

This function will not consume any resource if the resource is lower than the amount. meaning that consuming 50 breath when the player has 25 will cause the function to do nothing.

The function overConsumeResource() will do the opposite, meaning that it will consume the specified resource even if there isn't enough resource, and set it to 0 if the amount is higher than the remaining resources.

You can also block the usage of this function by locking a specific resource. You can do this by using the setResourceLocked() function

Parameter(s):

resource :

The name of the resource you want to consume.

Default resource names
breath
energyRegenBlock
energy
shieldHealth
health

amount :

The amount resource(s) that will get consumed if the user has enough of it.
Obviously, this value can't be negative.

Retun:

bool :

A boolean variable indicating if the player has enough of the specified resource.
True if the player had enough.
False if the player didn't

Example:

-- instead of doing this
if status.resource("sheildHealth") >= 20 then
    status.consumeResource("shieldHealth", 20);
    --insert script here
else
    world.logInfo("Your shield would probably explode and injure you.");
end
-- just do this
if status.consumeResource("sheildHealth", 20) then
    --insert script here
else
    world.logInfo("Your shield would probably explode and injure you.");
end

isResource(String resource) : bool

Description:

This function will check if a given string is the name of a resource such as energy or health.

Parameter(s):

resource :

A string value that might be the name of a resource.
Fun fact: you can get all the resources name by listing the

Default resource names
breath
energyRegenBlock
energy
shieldHealth
health

Retun:

bool :

A value indicating wether or not the string was the name of a resource. it will be true if the string is the same as the name of a resource. it will be false if the string does not correspond to any resource name.

Example:

-- assuming input contains a string.
if status.isResource(input) then
    world.logInfo("My riddle, you have solved.");
then
    world.logInfo("My riddle, you haven't solved");
end

modifyResource(String resource, float differance) : float

Description:

This function will modify the value of a specified resource such as energy or health.
If the difference is positive and ends up over 100%, it will simply set the resource to it's maximum value.
If the difference is negative and ends up under 0%, it will simply set the resource value to 0.
You can simply write -[InsertVariableNameHere] and the modification will be negative, same thing for a number.

Parameter(s):

resource :

the name of the resource you want to modify.

Default resource names
breath
energyRegenBlock
energy
shieldHealth
health

differance :

The value that will be added or subtracted from the resource value.

Retun:

float :

The value of the resource after modification.

Example:

if status.modifyResource("shieldHealth", 100) == status.resourceMax("sheildHealth") then
    world.logInfo("You've some how fully repaired your shield with pebbles!");
then
    world.logInfo("Somehow, the magical pebbles haven't fully repaired your sheild.");
end

modifyResourcePercentage(String resource, float percentageDifferance) : float

Description:

This function will modify the percentage value of a specified resource such as energy or health.
If the difference is positive and ends up over 100%, it will simply set the resource to it's maximum value.
If the difference is negative and ends up under 0%, it will simply set the resource value to 0.
You can simply write -[InsertVariableNameHere] and the modification will be negative, same thing for a number.

Parameter(s):

resource :

the name of the resource you want to modify.

Default resource names
breath
energyRegenBlock
energy
shieldHealth
health

percentageDifferance :

The percentage value that will be added or subtracted from the resource value.
The values goes form 0 to 1, 0 being 0% and 1 being 100%

Retun:

float :

The value of the resource after modification, not in percentage for some reason.

Example:

if status.modifyResourcePercentage("shieldHealth", -0.9) <= 0 then
    world.logInfo("Your shield is now useless! Just like when your are dead!");
then
    world.logInfo("Your sheild saved your live! You may now protect the shield.");
end

overConsumeResource(String resource, float amount) : bool

Description:

This function will consume a specified amount of a specified resource such as energy or health and returns a value indicating of the player had enough of the specified resource.

This function will consume any resource no matter how low the resource value is. If the amount is too high it will simply set the value to 0.

The function consumeResource() will do the opposite, meaning that it will not consume the resource if there isn't enough of the specified resource.

You can also block the usage of this function by locking a specific resource. You can do this by using the setResourceLocked() function

Parameter(s):

resource :

The name of the resource you want to consume.

Default resource names
breath
energyRegenBlock
energy
shieldHealth
health

amount :

The amount resource(s) that will get consumed if the user has enough of it.
Obviously, this value can't be negative.

Retun:

bool :

A boolean variable indicating if the player has enough of the specified resource.
True if the player had enough.
False if the player didn't

Example:

-- instead of doing this
if status.resource("sheildHealth") >= 20 then
    status.consumeResource("shieldHealth", 20);
    --insert script here
else
    world.logInfo("Your shield explodes in you frace and injures you.");
    status.overConsumeResource("health", 20);
end
-- just do this
if status.overConsumeResource("sheildHealth", 20) then
    --insert script here
else
    world.logInfo("Your shield explodes in you frace and injures you.");
    status.overConsumeResource("health", 20);
end

removeEphemeralEffect(String effect) : void

Description:

Removes An exising effect.

Parameter(s):

effect :

The name of the effect you want to remove.

Retun:

No Data Returned

Example:

status.removeEphemeralEffect("glow");
world.logInfo("Who shut down the sun?");

resetAllResources(String resource) : void

Description:

This function will reset a specified resource such as energy or health.

The value of the resource will be put back to it's maximum value and it's default lock state.

Default resource names
breath
energyRegenBlock
energy
shieldHealth
health

Parameter(s):

No parameters

Retun:

No data returned

Example:

status.setResource("energy", 50);
status.setResourceLocked("breath", true);
status.resetAllResources();

status.resource("energy") == status.resourceMax("energy") = true;
status.resourceLocked("breath") == false = true;

resetResource(String resource) : void

Description:

This function will reset a specified resource such as energy or health.

The value of the resource will be put back to it's maximum value and it's default lock state.

Parameter(s):

resource :

The name of the resource you want to reset.

Default resource names
breath
energyRegenBlock
energy
shieldHealth
health

Retun:

No data returned

Example:

status.setResource("breath", 50);
status.setResourceLocked("breath", true);
status.resetResource("breath");

status.resource("breath") == status.resourceMax("breath") = true;
status.resourceLocked("breath") == status.resourceMax("breath") = true;

resource(String resource) : float

Description:

This function will return the current value of a specified resource such as energy or health.

Parameter(s):

resource :

The name of the resource you want to know the current value of.

Default resource names
breath
energyRegenBlock
energy
shieldHealth
health

Retun:

float :

A float variable indicating the current value of the specified resource.

Example:

if status.resource("health") <= 0 then
    world.logInfo("G-G-G-GAME O-O-O-OVER!!!!");
else
    world.logInfo("VICTORY!");
end

resourceLocked(String resource) : bool

Description:

This function will check if a resource is locked, meaning that it's value can't be changed using the consumeResource() and/or overConsumeResource() functions.

As of 8th of August 2015, the date where this entry was written, a locked resource will still be consumed by the player during normal activities or if any function that modifies a resource value other than the ones stated before is involved by a LUA script.

You can set a resource as locked by using the setResourceLocked() function.

Parameter(s):

resource :

The name of the resource you want to know the maximum value of.

Default resource names
breath
energyRegenBlock
energy
shieldHealth
health

Retun:

bool :

A boolean indicating the locked state of the resource.
True if the resource is locked.
False if the resource isn't locked.

Example:

if status.resourceLocked("health") then
    world.logInfo("ALL YOUR LIFES ARE BELONGS TO US!");
else
    world.logInfo("ALL YOUR LIFES AREN'T BELONGS TO US!");
end

resourceMax(String resource) : float

Description:

This function will return the maximum value of a given resource such health and energy.

Parameter(s):

resource :

The name of the resource you want to know the maximum value of.

Default resource names
breath
energyRegenBlock
energy
shieldHealth
health

Retun:

float :

A float representing the maximum value of a given resource.

Example:

local var1 = status.resourceMax("health");
var1 = var1 - status.resource("health");
world.logInfo("you are missing "..tostring(var1).."HP");

resourceNames() : table<float>

Description:

this Function will list all the resources that a player has. This function can be use to get certain values out of the resource(String resource) function.

Parameter(s):

No Parameter(s)

Retun:

table<float>:

A table containing all the values of the statistic you might ever want.

Default resource names
positionresource name
1breath
2energyRegenBlock
3energy
4shieldHealth
5health

Example:

local var1 = status.resource(status.ressourceNames()[1]);
local var2 = status.resource("breath");

local var1 == var2 = true;

-- you can use this to list all the names in your log.
for pos,resName in pairs(status.resourceNames()) do
    world.logInfo(pos .. " : " .. resName);
end

resourcePercentage(String resource) : float

Description:

This Function will return the value of a specific resource in percentage.
The values goes form 0 to 1, 0 being 0% and 1 being 100%

Parameter(s):

resource :

The name of the resource you are testing for.

Default resource names
breath
energyRegenBlock
energy
shieldHealth
health

Retun:

float :

The value in percentage of the resource you are asking for.

Example:

if status.resourcePercentage("energy") < 0.25 then
    world.logInfo("WARNING! Energy levels are low!");
else
    world.logInfo("Energy levels are ok");
end

resourcePositive(String resource) : bool

Description:

This Function will check if a specified resource is positive.

Parameter(s):

resource :

The name of the resource you are testing for.

Default resource names
positionresource name
1breath
2energyRegenBlock
3energy
4shieldHealth
5health

Retun:

bool :

the result of the test. It will return true if the resource is positive.
It will return false if the resource is equal to 0 or less.

Example:

if status.resourcePositive("health") then
    world.logInfo("you are alive!");
else
    world.logInfo("Dun! Dun! Dun! You're dead");
end

setPersistentEffects(String name, table<JSON effect AND/OR String effect> effects OR JSON effect OR String effect) : void

Description:

This function will add a certain persistent effect that can be refered to by a specific name.

You can use clearPersistentEffects() and clearAllPersistentEffects() functions to remove the persistent effect from the player.

You can also use addPersistentsEffects() and addPersistentsEffect() to add to the value instead of setting it.

If you are adding a permanent effect using an already existing name it will add it this way :

Status effect name as a string
If the effect is already there, it will do nothing, if it isn't it will add it.
Using a JSON object
The stat value you give will replace the current player stat value.

Parameter(s):

Name :

The name of the permanant effect you will use to refer to it. it has literaly nothing to do with the files of the game, only with how you want to refer to this effect.

Effect :

A string or an JSON object containing a stat modification.

Using a JSON object
elements :
stat: the name of the stat
one of these :
amount :
A set amount will be added.
effectivePercentage :
Adds a percentage of the player's stat.
basePercentage :
Adds to the base value.
Status effect name as a string
If the effect is already there, it will do nothing, if it isn't it will add it.

Retun:

No Data Returned

Example:

-- Using a the name of an effect
 
status.setPersistentEffect("slowDeath","weakpoison");
 

 
-- Using a JSON argument with amount
-- Assuming fallDamageMultiplier has a value of 1 which means 100%
 
status.setPersistentEffect("longFallBoots",{ stat = "fallDamageMultiplayer", amount = 0});
-- the player will now recieve no fall damage.
 

 
-- Using a JSON argument with effectivePercentage
-- Assuming powerMultiplier has a value of 3 which means 300%, the 200% extra are from a piece of armor and the other 100% being the base power
 
status.setPersistentEffect("PowerPunch",{ stat = "powerMultiplier", effectivePercentage = 0.25});
-- the player powerMultiplier will now have a value of 375%
 
status.setPersistentEffect("PowerPunch",{ stat = "powerMultiplier", effectivePercentage = 0.25});
-- the player powerMultiplier will now have a value of 375%
 

 
-- Using a JSON argument with basePercentage
-- Assuming powerMultiplier has a value of 3 which means 300%, the 200% extra are from a piece of armor and the other 100% being the base power.
 
status.setPersistentEffect("weakerPunch",{ stat = "powerMultiplier", basePercentage = -0.25});
-- the player powerMultiplier will now have a value of 275%
 
status.setPersistentEffect("Punch",{ stat = "powerMultiplier", basePercentage = 0.25});
-- the player powerMultiplier will now have a value of 325%

setResource(String Resource, float value) : void

Description:

This function will set the value of a specified resource to a specified amount.

If you set the value too high, it will set the resource value to it's maximum.
If you set a negative value it will do nothing.

This function will still work if the resource has been locked using setResourceLocked().

Parameter(s):

resource :

The name of the resource you want to set the value of.

Default resource names
breath
energyRegenBlock
energy
shieldHealth
health

value :

The value that the specified resource will have once the function has been invoqued.

Retun:

No data returned

Example:

-- please don't do that, unless you want the player dead for some reason
world.logInfo("DIE YOU WILL!!! MUHAHAHAHAHAHAHAHAHA!!!!!!!!");
status.setResource("health", 0);

setResourceLocked(String resource, bool locked) : void

Description:

This function will lock the value of a specified resource.

When a resource is locked, the functions consumeResource() and overConsumeResource() won't work.

Parameter(s):

resource :

The name of the resource you want to set the locked state of.

Default resource names
breath
energyRegenBlock
energy
shieldHealth
health

locked :

A boolean representing the locked state of the specified resource.

Retun:

No data returned

Example:

-- If you do this
status.setResourceLocked("breath", true);
-- This won't work
status.consumeResource("breath", 25);

setResourcePercentage(String Resource, float value) : void

Description:

This function will set the percentage value of a specified resource to a specified amount.

If you set the value too high, it will set the resource value to it's maximum.
If you set a negative value it will do nothing.

This function will still work if the resource has been locked using setResourceLocked().

Parameter(s):

resource :

The name of the resource you want to set the value of.

Default resource names
breath
energyRegenBlock
energy
shieldHealth
health

value :

The value that the specified resource will have once the function has been invoqued.

The values goes form 0 to 1, 0 being 0% and 1 being 100%.

Retun:

No data returned

Example:

world.logInfo("POWER!!!!!!!!!!!!!!!!!!!!");
status.setResourcePercentage("energy", 1);

setStatusProperty(String property, any) : void

Description:

This function allows you to dynamically change a player propiety.

Parameter(s):

property :

The name of the propriety you want to change as a string.

any :

The new value for the propriety, it must be the same type of value as the previous propiety was.

Retun:

No Data Returned

Example:

status.setStatusProperty("ouchNoise","\\sfx\\gun\\rocketblast1.wav")
-- With that you will shurely have an explosive personality!

stat(String stat) : float

Description:

This function will search for an existing player statistic such as maximum health and energy regeneration and return the value of the statistic if it exists.

Parameter(s):

String stat:

The name of the statistic you want the value of. you can expand the list by creating your own statistic by simply adding a new status effect to an armor.

Default statistic names
maxHealth
maxEnergy
protection
grit
fallDamageMultiplier
breathRegenerationRate
breathDepletionRate
energyRegen

Retun:

float:

The value of the statistic you wanted.

If the value retuned is a zero you might have an error in your code since zero is the value returned for a statistic that does not exists or it might mean that the statistic has no value yet. A good example would be the protection statistic, since it has no value when you aren't wearing any armor.

Example:

local var1 = status.stat("maxHealth");
local var2 = status.stat("maxEnergy");
local var2 = status.stat("protection");

statPositive(String stat) : bool

Description:

This Function will check if a specified statistic is positive.

Parameter(s):

stat :

The name of the statistic you are testing for.

Default statistic names
maxHealth
maxEnergy
protection
grit
fallDamageMultiplier
breathRegenerationRate
breathDepletionRate
energyRegen

Retun:

bool :

The result of the test. It will return true if the statistic is positive.
It will return false if the statistic is equal to 0 or less.

Example:

if status.statPositive("protection") then
    world.logInfo("you are protected against the forces of evil!");
else
    world.logInfo("The forces of evil might crush you");
end

statusProperty(String property) : any

Description:

This function is used to find the proprieties of the player.

Parameter(s):

property :

The name of a wanted propriety as a string.

Retun:

any :

A variable or table containing the propriety you asked for.

Example:

local propriety = status.statusProperty("ouchNoise");
-- This will return the path to the ouch noise file of the player.