Lua API Reference

From Bonfire by Hogswild Prasetto
Revision as of 22:05, 24 May 2024 by Sonic260 (talk | contribs) (→‎Flags / Booleans: orc.penetrated definition clarification.)

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.


Scripts must be stored within the Lua sub-folder in your Bonfire directory, located at:

%appdata%/Prasetto/Bonfire/Mods/lua


If the Lua script contains the start() or update() functions, those will execute automatically.


Scripts can also be loaded from subdirectories 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 Orc_Follower/OF-API


Will inject the OF-API.lua file under the name of “Orc_Follower/OF-API,” and any execution commands must include the directory name:


oluacf Orc_Follower/OF-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

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.


Using oluaria with no parameters will stop all iterating scripts in the target's inventory.

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:

  • Upon injection via oluainj
  • If the code is saved within an orc's inventory, then immediately after the orc gets instantiated/spawned.


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

  • hairIndex - Takes an integer that refers to the hair type that gets affected:
    • 1 - Head
    • 2 - Beard
    • 3 - Chest
    • 4 - Limb
  • colorR - Red color channel, takes a floating value from 0 to 255.
  • colorG - Green color channel, takes a floating value from 0 to 255.
  • colorB - Blue color channel, takes a floating value from 0 to 255.
  • colorA - Alpha color channel, takes a floating value from 0 to 255. While this is currently unused, the parameter is still required.
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:

  • hairIndex - Takes an integer that refers to the hair type that will be checked:
    • 1 - Head
    • 2 - Beard
    • 3 - Chest
    • 4 - Limb
  • rgbIndex - Takes an integer referring to the color channel that will be returned:
    • 1 - Red color channel
    • 2 - Green color channel
    • 3 - Blue color channel
    • 4 - Alpha channel
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:

  1. SexAnal1
  2. SexOral1
  3. SexAnal2
  4. BedFap1
  5. SexOral2
  6. HandJob1
  7. FloorFap1
  8. Sex69
  9. GenieBlow2
  10. FloorLineFap1
  11. StandingAnal1
  12. PowerRide1

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:

  • 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

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:

  • Outback1
  • Inn1
  • Sea1
  • BathHouse
  • Library
  • Moraine
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.