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.

Command	Usage	Effect
oluainj	oluainj luaScriptName	Injects a Lua script within the console target's inventory. Scripts must be stored within the Lua directory, located at %appdata%/Prasetto/Bonfire/Mods/lua Scripts can also be loaded from sub-directories within the Lua folder, by separating the folder names with a “/”. Do note, however, that when the script gets injected, it will include the directory name. For example: oluainj OrcFollower/API Will inject the API.lua file under the name of “OrcFollower/API”. Any commands executing a function from the API script must include the directory name: oluacf OrcFollower/API,follow Warning: If the Lua script contains errors, the console will print the following message: "Error reading lua file: Incorrect format and/or syntax." This occurs when your script contains syntax errors, or is trying to manipulate a property within Bonfire that doesn't exist, or is marked as "read-only."
oluacf	oluacf luaScriptName,functionName	Executes a single function within an injected script once
oluaiifr	oluaiifr luaScriptName,functionName,duration	Causes a single function to iterate, and execute repeatedly for a set duration. When the duration is exceeded the iteration will stop. Tip: Setting duration to "Infinity" will make the script run forever.
oluaria	oluaria luaScriptName,functionName oluaria	Stops an iterating function within a Lua script. Using oluaria with no parameters will stop all iterating scripts on the console target.
oluarem	oluarem 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 upon injection AND whenever the holder enters a new scene. This is typically used for setting variables and preemptively granting data flags.

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: orc.orcobjective.istheplayer – Returns true if this objective is the player orc.orcobjective.height = 1.5 – sets the objective’s height to 1.5 It is also possible to store the objective in a separate variable: local target = orc.orcobjective target.istheplayer target.height = 1.5 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 player.
distancetoobjective	float	Returns the distance to the objective.

Positioning

Property Name	Type	Description / Usage
positionx positiony positionz	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
bodyfat	float
bodyhair	float
coatdensity	float
earshape	float
earsize	float
extrabutt	float
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
haircolor1_[r,g,b]	float	Hair Color A in the character editor Value range: -127.5 to 382.5
haircolor2_[r,g,b]	float	Hair Color B in the character editor Value range: -127.5 to 382.5
hairlength	float
handgirth	float
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
penisextra	float
penisgirth	float	Max is 4.0, but clamps to 2.0 during corruption
penisshower	float
penissize	float
skincolormid_[r,g,b,m]	float	Skin Color – Upper Layer Value range: -127.5 to 382.5
skincolortop_[r,g,b,m]	float	Skin Color – Sun Bleach Value range: -127.5 to 382.5
skincolorund_[r,g,b,m]	float	Skin Color – Lower Layer Value range: -127.5 to 382.5
tusksize	float

Note about the color attributes:

It is not know 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 forumula 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)
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

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

Orc Functions

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: The caster and target currently have mutual consent The caster and target are both in PVP mode This will always return "true" in single player mode.
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

Function Name	Return Type	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.
fapstart	void	Makes the instance fap.
fapstop	void	Stops the instance from fapping.
sexanal1	void	Starts the doggy style sex scene at the nearest circle.
sexanal2	void	Starts the missionary style sex scene at the nearest circle.
sex69	void	Starts a 69 where the instance is standing

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.
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)

Misc Functions

Function Name	Return Type	Usage	Description
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.
Buffs	void	buff(orc:Orc,buffName:string,duration:float,strength:int) buffperma(orc:Orc,buffName:string,strength:int)	Applies a buff on the Orc instance with the set duration. Setting the strength will act as a multiplier. Note: When buffs are applied to the player this way, it will not create a buff icon. Note 2: Buffs applied this way do not consume mana.
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.
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.
luaiterator	void	luaiterator(scriptName:string, functionName:string, duration:float)	Executes and iterates a function within a script, for a set duration. Use orc.infinity to make the script run forever
remscript	void	remscript(scriptName: string)	Removes the specified script from this instance's inventory
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. 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.
walk2clear	void	walk2clear()	Stops the orc if they're currently walking.
jump	void	jump(strength:float)	Makes the instance jump. Strength is a value from 0 to 1.

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)
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: Outback1 Inn1 Sea1 BathHouse Library Moraine

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
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