Lua API Reference
This page contains documentation for all the known functions within the Lua Bonfire API. For more information for running Lua code in Bonfire, please see the Lua scripting page. Assume this page is up to date with the latest Patreon release.
Lua Console Commands
This table comprises the list of Lua-related console commands to actually inject, run, or even delete scripts from the console target's inventory. These can be placed into a scroll, macro, or NPC's CustomCall action during dialogue.
Each of the below commands have a Lua-counterpart for executing functions in-code. See the Code Execution / Management function below.
Command | Usage | Effect |
---|---|---|
qorclua | qorclua Lua Code Goes Here
Ex: qorclua orc.consolecommand("quickgrow1") |
Allows you to easily execute Lua code directly from the console.
This creates a temporary lua script into the target's inventory that gets deleted after execution has completed. |
oluainj | oluainj luaScriptName
or oluainj folderName/luaScriptName |
Injects a Lua script within the console target's inventory.
%appdata%/Prasetto/Bonfire/Mods/lua
|
oluacf | oluacf luaScriptName,functionName
or oluacf directoryName/luaScriptName,functionName |
If the target contains luaScriptName within their inventory, it will execute functionName once, if it exists. |
oluaiifr | oluaiifr luaScriptName,functionName,duration
or oluaiifr directoryName/luaScriptName,functionName,duration |
Causes a single function to iterate and execute repeatedly for a set duration in seconds. When the duration is exceeded the iteration will stop.
Tip: Setting duration to "Infinity" will make the script run forever. |
oluaria | oluaria luaScriptName,functionName
or oluaria directoryName/luaScriptName,functionName or oluaria |
Stops a function from iterating.
|
oluarem | oluarem luaScriptName
or oluarem directoryName/luaScriptName |
Removes the Lua script from the target's inventory. This will also stop any related iterators. |
Automatic Functions / Code
This code will execute automatically when injected into the target's inventory using the oluainj command or when using the luacopyover() function. This removes the need to run functions manually with oluacf or oluaiifr. Note: The start() and update() functions will not run automatically if the script is injected through a OrcLuaScript action within macros.
Function Name | Return Type | Description /Usage |
---|---|---|
start | void | The start() function will execute once upon injection. |
update | void | The update() function will start an iterator that runs for Infinity upon injection. |
[chunk space] | N/A | “Chunk Space” refers to any code lying outside of a function within a Lua file.
This code will execute once under either condition:
|
Orc Properties
These are properties--or variables--belonging to an Orc instance, and are accessible by writing orc.* before every call. In all cases "orc" will always refer to the instance who is running the script from within their inventory. For example: "orc.istheplayer" returns "true" if this orc is the player, and "orc.height = 1.5" sets this orc's height to 1.5.
Targeting
Property Name | Type | Description / Usage |
---|---|---|
orcobjective | Orc | Returns this instance’s current “target” as another Orc instance. Functions and properties can be called on the other instance by calling orc.orcobjective.* before every command:
It is also possible to store the objective in a separate variable:
Warning: An instance’s objective changes frequently, so it is recommended that you store the objective in a separate variable as soon as possible for reference. The objective can also return ‘nil’, so it is recommended that you first perform a nil check before attempting to call a function or property on them. |
canseeorcobjective | bool | Returns true if the objective (this instance’s current “target”) is within line of sight |
canseeinterest | bool | An “interest” is like a lighter version of “objective." It refers to the orc our instance is looking at, but not necessarily targeting. |
istheplayer | bool | Returns true if instance is the local player (ie: YOU, the person playing the game with the keyboard and mouse or controller.) |
isnetworkedplayer | bool | For use online. Returns true if the instance is another player. |
isnetworkednpc | bool | For use online. Returns true if the instance is a spawned npc. |
distancetoobjective | float | Returns the distance to the objective. |
Positioning
Property Name | Type | Description / Usage |
---|---|---|
|
float | The instance’s current x, y, or z position in the world. |
Physical Attributes
Unless stated otherwise in the description, the value range for most attributes will be between 0.0 and 1.0.
Property Name | Type | Description / Usage |
---|---|---|
ballsize | float | Max is 2.0 |
beardlength | float | |
beardstubble | float | |
beardstyle | int | Sets or returns an orc's beard style without changing the length.
However, invalid values will make the orc shaved and have a length of 0. Beard styles are integer numbers (0, 1, 2, 3...) |
bodyfat | float | |
bodyhair | float | |
coatdensity | float | |
earshape | float | |
earsize | float | |
extrabelly | float | |
extrabutt | float | |
extralats | float | |
extralegs | float | |
extrapecs | float | |
eyecolor_get() | int | An orc function to get the numerical value of a specific eye color channel. To use it write:
orc.eyecolor_get(RGBIndex:int) In the place of RGBIndex, you would pass in a value between 1-4, which corresponds to the Red, Green, Blue, and Alpha channels respectively. |
eyecolor_set() | void | An orc function to set the numerical value of a specific eye color channel. To use it write:
orc.eyecolor_set(colorR:int, colorG:int, colorB:int, colorA:int) All parameters would be an integer value between 0-255. |
footsize | float | |
hair() | void | An Orc Function to set the instances's hair style. To use it, write:
orc.hair(id:int, length:float) Where id is the hair style, and length is a value from 0 to 1.0 |
Hair Color SET Functions | void |
A pair of Orc Functions to set the colors of an instance's hair. Color A will set the Upper Layer while Color B sets the Lower Layer. To use them write either: orc.HairColorA_Set(hairIndex:int, colorR:int, colorG:float, colorB:int, colorA:int) orc.HairColorB_Set(hairIndex:int, colorR:int, colorG:int, colorB:int, colorA:int) An explanation of the parameters:
|
Hair Color GET Functions | int |
A pair of Orc Functions that will return the R, G, or B color values of an instance's hair. Color A will get the Upper Layer while Color B get the Lower Layer. To use them write either: orc.HairColorA_Get(hairIndex:int, rgbIndex:int) orc.HairColorB_Get(hairIndex:int, rgbIndex:int) An explanation of the parameters:
|
hairlength | float | |
handgirth | float | |
hairstyle | int | Sets or returns an orc's hair style without changing the length.
However, invalid values will make the orc bald and have a length of 0. Hair styles are integer numbers (0, 1, 2, 3...) |
horns | int | Sets an orc's horn style. Available styles are between 0 and 4, where 0 results in an orc with no horns. |
headcrown | float | |
height | float | Max is 1.5, but clamps to 1.0 during stage 1 of corruption. |
jawsize | float | |
jawsizeraw | float | 0 maxes out the jaw size while 1 reduces it |
lipgirth | float | |
muscle | float | |
nipplesize | float | |
penisextra | float | |
penisgirth | float | Max is 4.0, but clamps to 2.0 during corruption |
penisshower | float | |
penissize | float | |
scleracolor_get | int | An orc function to set the numerical value of a specific eye sclera color channel. To use it write:
orc.scleracolor_set(colorR:int, colorG:int, colorB:int, colorA:int) All parameters would be an integer value between 0-255. |
scleracolor_set | void | An orc function to set the numerical value of a specific eye sclera color channel. To use it write:
orc.scleracolor_set(colorR:int, colorG:int, colorB:int, colorA:int) All parameters would be an integer value between 0-255. |
skincolormid_* | float |
Skin Color – Upper Layer Value range: -127.5 to 382.5 Note: Replace the * with r,g,b or m to target the Red, Green, Blue, and Metal properties. |
skincolortop_* | float |
Skin Color – Sun Bleach Value range: -127.5 to 382.5 Note: Replace the * with r,g,b or m to target the Red, Green, Blue, and Metal properties. |
skincolorund_* | float |
Skin Color – Lower Layer Value range: -127.5 to 382.5 Note: Replace the * with r,g,b or m to target the Red, Green, Blue, and Metal properties. |
tusksize | float | |
snout | float | Amount of Iguapi (gorilla-like) mouth protusion. Will also affect foot shape. Max is 2.0 |
Note about the color attributes:
It is not known why the value range for colors is from -127.5 to 382.5, but you can convert this to the standard RGB range with the following formula:
The difference between -127.5 and 382.5 equals 510. Divided by 2, this is 255, which is the maximum value in RGB notaton.
So, the conversion formula is as follows:
color = (rgbNum * 2) - 127.5
Where rgbNum is the value chosen from a color picker.
Please note that the select layer color will blend with the layers below it, and is influenced by the "metalness" value, which can cause colors to appear off, even when using this formula.
Flags / Booleans
Property Name | Type | Description / Usage |
---|---|---|
afterglowing | bool | Returns true if the instance is afterglowing right after orgasming during a sex scene |
busywalking | bool | Returns true if the instance is currently walking to a destination |
cumming | bool | Returns true if, during a sex scene, the instance is orgasming |
genitalsconcealed | bool | Returns true if the instance's genitals are hidden, and false if they are visible (Not necessarily naked, such as pants ripping) |
immutable | bool | Returns true if this instance is either a ghost or special character that cannot be altered by transformation spells nor corruption |
isairborne | bool | Returns true if the instance is floating in mid air |
isbusy | bool | Returns true if the instance is doing literally anything else besides standing |
isfapping | bool | Returns true if the instance is doing a standing fap. (Does not apply to Self-Action, or solo fapping on the Inn or Island Beds) |
isfusion | bool | Return true if the instance is a fusion |
isgeniefragment | bool | Returns true if this instance is an NPC genie fragment (ie: Eves, Levi; not a geniefied orc) |
isghost | bool | Returns true if the instance is a ghost |
issexing | bool | Returns true if the instance is in a sex animation (This includes Self-Action, and Handjobs in the Bath House) |
sextop | bool | Returns true if the instance is in the controlling position of the sex act, typically the "top" in most cases. |
penetrated | bool | For the standalone sex acts (Standing Anal, Powerride, etc), Returns true if the instance is in the receiving position of the sex act, AND they are currently being penetrated.
Caution: For older sex animations (stone bed missionary, stone bed anal, handjob), this value will always return true regardless if the instance is topping or not. |
istalking | bool | Returns true if the instance is in a dialogue |
onatask | bool | Returns true if the instance is busy doing some task like casting a spell or sexing |
perfectglowing | bool | Returns true if the instance has achieved a perfect synchronized orgasm during a sex scene |
iscorechr | bool | Returns true if the instance is one of the vanilla NPCs (Celik, Oriol, Bo, etc...) |
retbool | bool | This is a special static boolean that is present in all Lua scripts, regardless if it's referenced directly or not.
This boolean is mainly used for Execution Conditions in dialogue editor that check if a function within a lua script the NPC or player is carrying returns true or false. Since the Lua implementation currently cannot parse return values between the script and dialogue editor, in its place you need to set retbool to equal either true or false in the function. |
Misc Properties
Property Name | Type | Description / Usage |
---|---|---|
arousal | float | Returns the instance’s current arousal level.
The value range is 0.0 – 1.0 |
corruption | float | Returns the instances level of corruption.
The value range is 0.0 – 3.0, where 1.0 is the cap before becoming a genie |
infinity | float | Returns a floating number representing infinity. |
orcname | string | The instance’s name |
modspeechname | string | If an orc's dialogue was replaced with the modspeech command, this returns the name of the new dialogue.
Otherwise, if the orc's dialogue was not changed at all, it just returns nil. |
sextype | int | Returns an integer corresponding to the current sex act occurring, returning -1 if no sex is happening at all.
The values are below:
|
Orc Functions
Code Execution / Management
These are functions that allow you to call lua functions in other scripts, start or stop iterators, etc. They're equivalent to the oluacf and the oluaiifr console commands.
Function Name | Return Type | Usage | Description |
---|---|---|---|
luacallfunction | void | luacallfunction(scriptName:string,functionName:string) | Executes a function within a script that matches the specified name. |
luaiterator | void | luaiterators(scriptName:string, functionName:string, duration:float) | Executes and iterates a function within a script, for a set duration in seconds.
Use orc.infinity to make the script run forever |
remiterators | void | remiterators(scriptName:string, functionName:string) | Stops iterating the specified function within a script. |
luacopyover | void | luacopyover(a:Orc, b:Orc, scriptName:string) | Copies a lua script from a’s inventory to b’s inventory, if it exists.
During online play, this function will not run if a and b do not share mutual consent, or are outside of PVP mode. |
remscript | void | remscript(scriptName: string) | Removes the specified script from this instance's inventory |
Targeting
Function Name | Return Type | Usage | Description |
---|---|---|---|
canaffect | bool | canaffect(caster:Orc,target:Orc) |
Returns "true" or "false" in an online setting if the caster instance is allowed to use commands on the target instance. This function returns true if:
|
findclosest | Orc | findclosest(range:float) | Returns an Orc instance within a set range. Returns nil if none is found. |
findnextclosest | Orc | findnextclosest(range:float, target:Orc) | Returns an Orc instance within range of another instance. Returns nil if none is found. |
getclosest | void | getclosest(range:float) | Changes this instance’s current objective to the closest orc in range. orcobjective will be nil if none is found. |
getclosestpureorc | void | getclosestpureorc(range:float) | Changes this instance’s current objective to the closest, non-corrupted instance in range. orcobjective will be nil if none is found. |
orcobjset | void | orcobjset(orcName:string) | Set this instance’s current objective to the orc with a name matching orcName. orcobjective will be nil if none is found. |
Sex
Many of the functions that initiate sex will take an optional target parameter set to another Orc instance. If this instance is nil or if no argument is passed in, the orc instead will attempt to start sex with their orcobjective, if present.
Function Name | Return Type | Usage | Description / Usage |
---|---|---|---|
cum | void | The instance will cum once. If this occurs during sex, this will contribute to the orgasm meter. | |
endsex | void | This instance will stop sexing. | |
swapsex | void | Swaps the top and bottom during sex | |
fapstart | void | Makes the instance fap. | |
fapstop | void | Stops the instance from fapping. | |
sexanal1 | void | sexanal1()
sexanal1(target:Orc) |
Starts the doggy style sex scene at the nearest circle. |
sexanal2 | void | sexanal2()
sexanal2(target:Orc) |
Starts the missionary style sex scene at the nearest circle. |
sexdoggy1 | void | sexdoggy1()
sexdoggy1(target:Orc) |
Starts the standing doggy style scene where the orc is standing. If no parameter is specified, the orc will instead play the "invite" pose. |
sex69 | void | sex69()
sex69(target:Orc) |
Starts a 69 where the instance is standing |
sexoral1 | void | sexoral1()
sexoral1(target:Orc) |
Starts the standard oral scene. |
Data Flags
Function Name | Return Type | Usage | Description |
---|---|---|---|
hasitemflag | bool | hasitemflag(flagName:string, flagData:string) | Returns “true” if the instance has a data called flagName, regardless of its actual value. |
ifitemflag | bool | ifitemflag(flagName:string, flagData:string) | Returns “true” if the instance has a data flag called flagName, with a value matching flagData. |
setitemflag | void | setitemflag(flagName:string,flagData:string) | Sets the value of a data flag called flagName to flagData. If this flag doesn’t exist, a new flag matching flagName will be created. |
remitemflag | voit | remitemflag(flagName:string) | Deletes the dataflag called flagName from the instance's inventory. |
itemflagstring | string | itemflagstring(flagName:string) | Returns a data flag's stored value as a string. |
itemflagfloat | float | itemflagfloat(flagName:string) |
Returns a data flag's stored value as a float. If the value is not a valid float, Lua returns 0. |
itemflagint | int | itemflagfloat(flagName:string) |
Returns a data flag's stored value as an integer. This function will not convert an float into an integer. If the value is not a valid integer, Lua simply returns 0. |
Sounds
These functions will play an in-game sound, with a volume level between 0.0 and 1.0
Function Name | Return Type | Usage |
---|---|---|
soundbrass | void | soundbrass(volume:float) |
soundbreath | void | soundbreath(volume:float) |
soundbreathlesser | void | soundbreathlesser(volume:float) |
sounddeepbreath | void | sounddeepbreath(volume:float) |
sounddeepbreathlesser | void | sounddeepbreathlesser(volume:float) |
soundtimpani | void | soundtimpani(volume:float) |
Buffs
Function Name | Return Type | Usage | Description |
---|---|---|---|
buff | void | buff(target:Orc, buffName:string, duration:float, strength:int) | Applies a buff on the Orc instance with the set duration in seconds. Setting the strength will act as a multiplier.
As of version 0.50.X buffs cast through this way cost mana and MUST be known by the orc instance calling the function. The target however, does not need the relevant buff knowledge unless they are the same orc as the caster. |
buffperma | void | buffperma(target:Orc, buffName:string, strength:int) | Same as buff but permanent. This is expensive to use. |
knowsbuff | bool | knowsbuff(buffName:string) | Returns true or false if the orc instance knows the buffName used. |
teachbuff | void | teachbuff(buffName:string, target:Orc) | Makes the instance teach another orc the specified buffName, provided the instances knows it first. |
Misc Functions
Function Name | Return Type | Usage | Description |
---|---|---|---|
debuglog | void | debuglog(text:string) | Prints debugging messages into the "output_log.txt" log file located in the Bonfire_Data folder.
(This is located in the same spot as your Bonfire.exe) |
consolecommand | void | consolecommand(command:string) |
Executes a console command (including a batch command). The default target is the Orc instance calling the function. During online play, this function cannot be used on Orcs who do not share consent with the caster, or are outside of PVP mode. |
forcerotation | void | forcerotation(x:float, y:float, z:float) | Rotates the orc. Note: It is recommended that you only rotate on the y-axis. Rotating on x or z could tilt the orc. |
tp2pos | void | tp2pos(x:float, y:float, z:float) | Warps the instance to the x, y, and z coordinates specified |
walk2orc | void | walk2orc(target:Orc, duration:float, speed:float, allowInterruptions:boolean) | Makes this orc walk towards their target. duration indicates when the function should cancel if a number of seconds passes. speed determines the orcs movement speed (Where 1 is a slow walk, and 10 is a sprint). allowInterruptions determines whether this orc can be spoken to while they're walking. |
walk2loc | void | walk2loc(x:float, y:float, z:float,
duration:float, speed:float, allowInterrupt:bool) |
Similar to orc.walk2loc but makes them walk to a specific x,y,z coordinate, rather than a specific orc. |
walk2clear | void | walk2clear() | Stops the orc if they're currently walking. |
fullstop | void | fullstop() | Completely stop stops the orc and resets them to their idle animation if they were walking. |
jump | void | jump(strength:float) |
Makes the instance jump. Strength is a value from 0 to 1. |
say | void | say(message:string) | Displays a textbox over the orc displaying a message |
wearsitem | bool | wearsitem(itemID:int) | Returns true or false if the orc is wearing a piece of equipment with the matching itemID. |
containsfuseename | bool | containsfuseename(name:string) | Returns true or false if the orc is currently fused with the name specified |
translate | void | translate(x:float, y:float, z:float) | Slides the orc a specified amount in the x, y, or z direction. |
Orc.Game Properties
These are special commands that access internal, game-related properties within Bonfire. They can all be accessed by typing orc.game.* before each call. For example, to pull up a random integer, you would write orc.game.randomInt(1,10) to pull a random integer between 1 and 9.
Property Name | Type | Description / Usage |
---|---|---|
deltatime | float | A Unity property representing the elapsed time--in seconds--since the last frame.
This is useful for scripts that rely on tracking time. More information can be found in the Unity Scripting API here: |
consoleasset | Asset | Returns the last asset created with the asset console command. |
networked | bool | returns true if the instance is playing online |
nextscene | string | Returns the current scene, or captures the name of the upcoming scene when using the travel command, or walking through a portal. |
Orc.Game Functions
Function Name | Return Type | Usage | Description |
---|---|---|---|
backeaseinout | float | backeaseinout(value; float) | Takes a value between 0.0 and 1.0 and returns a cubic curve between the two numbers that is close, but not equal to, either. Intended to be used with lerp |
cos | float | cos(value:float) | Returns the cosine |
sine | float | sin(value:float) | Returns the sine |
cycle | float | cycle(value:float, length:float) | Based on the Mathf.Repeat() function in Unity. It returns the modulo (%) of two numbers, except this works for floating point numbers as well. It does not allow negative inputs. |
flatstutter | float | flatstutter(value:float) | Same as backeaseinout, except the number jerks as it approaches either end. |
lerp | float | lerp(min:float, max:float, speed:float) | Linearly interpolates between two values at a specified speed. |
movetowards | float | movetowards(value1:float, value2:float, rate:float) | Returns a number between value1 and value2, increased by rate. Useful for creating a growth script where an attribute increases to the max level. |
randomint | int | randomint(min:int, max:int) | Returns a random integer between the min value and the max value (exclusive) |
randomfloat | float | randomfloat(min:int, max:int) | Returns a random floating point between the minimum value and the maximum value. |
distancebetweenorcs | float | distancebetweenorcs(orcA:Orc, orcB:Orc) | Returns the distance between two orc instances |
orcfromcommandname | Orc | orcfromcommandname(orcName:String) | Returns an orc named orcName from within the current scene, without changing the orc’s interest or objective in the process. |
sceneis | bool | sceneis(sceneName:String) | Returns true if if the instance is standing in the sceneName specified.
The available scenes are:
|
setsceneflag | void | setsceneflag(flagName:String, flagData:String) | Saves or changes a special data flag onto the current scene. Used mostly for conditional checks.
This flag does not appear in the inventory, and is therefore a temporary variable that will be deleted when the scene changes. |
ifsceneflag | bool | ifsceneflag(flagName:String, flagData:String) | Used to check a scene flag's value. It will return false if the flag does not exist. |
infodialogue | void | infodialogue(message:String) | Prints a message on the middle of the screen. If used online, this will appear for all players. |
daytime | void | daytime(hour:float) | Similar to the daytime console command. Sets the current hour of the day, using a floating value between 0 and 24. |
moonorbit | void | moonorbit(moonphase:float) | Similar to the moonorbit console command. Sets the current moon phase between 0 and 1.0, where both extremes are a new moon, and 0.5 is a full moon. |
Asset Properties
These functions affect assets that have been spawned within the game. To invoke them, you would write assetVariableName.assetFunction(). At the moment, not much is known about asset manipulation, so the amount of known commands is limited.
Property Name | Type | Description / Usage |
---|---|---|
game.consoleasset | Asset | Returns the last asset created with the asset console command. |
Asset Functions
Function Name | Return Type | Usage | Description |
---|---|---|---|
distancetoasset | float | game.distancetoasset(target:Orc, spawnedAsset:Asset) | Returns the distance between the Orc instance and a specific asset |
rotate | void | rotate(x:float, y:float, z:float, local:bool) | Rotates the asset on the x, y, and z axis. Local determines if this rotation occurs on the asset’s local axis. |
translate | void | translate(x:float, y:float, z:float, locaI:bool) | Moves the asset on the x, y, and z axis. Local determines if this rotation occurs on the asset’s local axis. |
Event Listeners
Events listeners are functions that execute automatically in response to an in-game event, but they will only activate if you EXPLICITLY write them in your lua script.
Use these to perform special operations before or after a particular event occurs.
Function Name | Executes When |
---|---|
onrightclick | As of version 0.47.6, Lua Scripts can be right-clicked in the inventory. When this happens, the code under this listener will be executed. |
onfusionasguest | When this orc becomes a fusee or "guest" in another orc's fusion. |
onfusionashost | When this orc absorbs another orc in a fusion |
onscenechange | Executes just before the scene changes |
onscenechanged | Executes after a scene change completes |
onsave | When the game is saved |
ongameexit | When the game is closed manually |
oncursed | When the orc's corruption property is greater than 0 |
ongeniefied | When the orc's corruption property is 3.0 |
ondefeat | When the orc has been defeated in combat. |
onwin | When the orc defeats another orc in combat. |
onhump | During sex, and while topping, when you click the mouse to thrust. |
onhumped | During sex, and while bottoming, when the top thrusts. |
oncum | Whenever an orc cums. |