-
Notifications
You must be signed in to change notification settings - Fork 4
Lua Scripts
In the editor, you can select "Custom Challenge", which allows you to write lua scripts to make basic custom challenges.
Disclaimer: The Lua scripting system is designed for creating custom challenge maps, not for custom items/npcs/etc or making Hide and Seek maps. (So don't ask for Happy Baldi and stuff.)
Lua scripts have some optional functions, and some required ones. You MUST have the required functions in your script or you will get errors.
Note that some of the required functions may not have globals defined yet, which means trying to call any self function or any function listed here will not work and throw an error.
- Initialize()
- SetupPlayerProperties()
- ExitedSpawn()
- Update(delta)
- AllNotebooks()
Called when the level is initialized. This is the first method that is called where all globals have been defined.
Called before initialized, globals are still undefined. The table returned is used to modify the player's movement variables. If you don't want to change a value from the default, don't include it in the table.
Below is an example function that has all the values at their default.
function SetupPlayerProperties() return { walkSpeed=16, runSpeed=24, staminaDrop=10, staminaMax=100, staminaRise=20 } end
This is called when the player leaves the elevator. It is recommended you call self:SpawnNPCs() and self:StartEventTimers() here, but you do not have to.
This is called every update frame/tick. Delta is the delta time, which is the time that passed inbetween this update and the last one. You can use it to make timers.
This is called when the player has collected all notebooks. For most challenges, you want to call self:OpenExits(true) here.
- NotebookCollected(notebookPosition)
- AngerBaldi(value)
- AllNPCsSpawned()
- OnItemUse(itemId, slot)
- GiveRandomSticker(packTypeId, total)
- OnLevelCompleted()
- NoiseMade(position, value)
- BaldiSlapped(baldi)
- OnActivityProgress(room)
- OnActivityCompletion(room, correct)
This is called whenever a notebook gets collected. notebookPosition is the notebook's position in world space.
This is called whenever the game wants to make Baldi angry. The return value of this function can be used to change how angry Baldi gets. Below is an example function that makes Baldi get twice as angry.
function AngerBaldi(value) return value * 2 end
BB+ only spawns NPCs if the player isn't too close. This function is called when every single NPC has spawned in for the first time. This is not called if SpawnNPCs is called multiple times.
Called when the player attempts to use an item. The return value determines if the item can be used. Returning true allows the item to be used while returning false prevents it from being used.
Called when the game attempts to give the player a random sticker of the specified pack type. (Refer to the cheat sheet). Total is the amount of stickers that are being given. Does not get called when self:GiveRandomSticker is called. Returning false cancels the default behavior, which can be used to alter the sticker given or amount of stickers using self:GiveRandomSticker.
Called when the level is about to be completed, returning a string will change the ending message.
Called whenever a noise is made. position is a Vector3, and value is the noise value.
Called whenever Baldi slaps. baldi is the Baldi that slapped.
Called whenever progress is made on an activity. room is the room with the activity.
Called when an activity is completed. correct is whether or not it was done correctly, room is the room with the activity.
Global Variables:
- player - The current Player.
Global Functions:
- Vector3(x,y,z) - Creates a new Vector3 with the specified x, y, and z coordinates.
- IntVector2(x,z) - Creates a new IntVector2 with the specified x and z coordinates.
- Color(r,g,b) - Creates a new Color with the specified r, g, and b values. (0-255)
- RandomDecimalNumber(min, max) - Generates a random decimal number between min and max, unlike math.random which can only generate integers.
You may have seen the "self" variable being used. This refers to BB+'s game manager, which is what your script is managing. You cannot add custom variables to self. (You can define variables in the global scope/outside a function if you want custom variables)
Spawns all the NPCs that were placed in the editor.
Starts the events and the level timer. This can only be called once.
This gets the current Baldi. If there are multiple it returns the first one it finds, which is usually the first one spawned. This can return nil if Baldi hasn't been spawned yet.
This starts the event with the specified event id, with the id being the id used in the level loader. The time is how long the event lasts, if it is 0 or below, the time will be randomly chosen in the same way as the regular random events. If doJingle is true, the usual event fanfare will occur with Baldi announcing it on the TV. Otherwise, the event will just happen instantly.
Returns the current NPC timescale.
Returns the current Environment timescale.
Returns the current Player timescale.
This opens all the exits, making completing the level possible. If doEscape is true, the standard exit sequence will play out. If it is false, all exits can be entered like in the tutorial. Sets escapeSequenceActive to true.
This returns a random cell that is safe for entites to be on.
Position can be either a Vector3 or an IntVector2. This gets the cell at the corresponding position.
Returns a table of all the rooms in the map.
Returns a table of all lights on the map.
This makes noise that Baldi and others can hear at the specified position and noise value.
This gets the first NPC with the specified the ID. The ID being the ID for the NPC in the level loader.
This spawns and returns the NPC at the specified Vector3 position. The ID being the ID for the NPC in the level loader.
This gets all NPCs on the map and returns them in a table.
This makes all activities activate their bonus problems. If includeLast is true, this will also activate bonus problems on the most recently completed machine.
This forcefully ends the game, showing the Baldi jumpscare animation.
This causes the level to be instantly completed with the specified text. If text is not passed in, the default win message is used.
Give a number of stickers determined by total, from the specified sticker pack (packTypeId, refer to cheat sheet).
Spawns an item with itemId at the specified Vector3 position. Does not work correctly with sticker packs.
Plays the specified vanilla SoundObject globally.
This variable is the amount that Baldi will get angry by when you collect a notebook. If you collect a notebook before Baldi is spawned, this value will get changed.
This gets the currently collected amount of notebooks.
This gets the total amount of notebooks on the map.
This variable is the current npc timescale modifier. (not the current npc timescale) Changing this value will speed up or slow down the speed of npcs.
This variable is the current environment timescale modifier. (not the current environment timescale) Changing this value will speed up or slow down the speed of the environment.
This variable is the current player timescale modifier. (not the current player timescale) Changing this value will speed up or slow down the speed of the player.
This variable determines if the escape sequence is active. In this context, it means whether or not elevators should start going Out Of Order. Automatically set to true when OpenExits is called.
Refers to the elevator manager. Refer to it's dedicated section.
NPC Functions:
- AddArrow(r,g,b)
- Squish(time)
- Unsquish()
- IsHidden()
- GetForward()
This adds an arrow onto the map that tracks this NPC with a color of the specified R G and B values. (0-255)
Squishes the NPC for the specified amount of time.
Unsquishes the NPC.
Returns true if the NPC is hidden.
Returns the NPC's forward vector.
NPC Variables:
- moveSpeedMultiplier
- position
- id
- squished
- direction
- objectName
This variable is a multiplier to the NPC's movement speed, higher values make the NPC faster while lower values make the NPC slower.
This is the variable that stores the NPC's id.
This is the NPCs current position. Changing this will teleport the NPC to the specified coordinates.
Returns if the NPC is currently squished. If it is set to true, the NPC will be squished for an infinite amount of time. Calling Unsquish or setting squished to false would be required to unsquish.
The direction the NPC is facing/its rotation on the y axis.
The name of the NPC's GameObject. Useful for identifying NPCs even if id is "unknown." Can be set.
Baldi shares all the functions and variables with NPCs. But he also has the additional functions:
- AddAnger(amount)
- SetAnger(amount)
- Praise(time)
- Slap()
This increases Baldi's anger by the specified amount. This does not call AngerBaldi.
This sets Baldi's anger to the specified amount. This does not call AngerBaldi.
This makes Baldi congratulate/praise the player for the specified amount of time.
Forces Baldi to slap his ruler.
The player refers to well, the player. Items are referenced by id, which is the id of the item in the level loader. Slot indexes start with 1 being the first slot, 2 being the second slot, etc.
Variables:
- position
- slotCount
- points
- moveSpeedMultiplier
- stamina
- staminaNormal
- baseWalkSpeed
- baseRunSpeed
- baseStaminaMax
- baseStaminaDrop
- baseStaminaRise
- walkSpeed
- runSpeed
- staminaMax
- staminaDrop
- staminaRise
- squished
- direction
The player's current position, setting this will teleport the player.
The player's current inventory size. Setting this calls SetSlotCount.
The player's current amount of YTPs. Setting this will show the YTP incrementing/decrementing animation.
This variable is a multiplier to the player's movement speed, higher values make the player faster while lower values make the player slower.
This variable is the player's current stamina.
This variable is the player's current stamina divided by max stamina, where 1 is always the current max stamina. Can be set as well.
The player's walk speed. Cannot be set.
The player's run speed. Cannot be set.
The max amount of stamina the player can naturally regenerate. Cannot be set.
The amount stamina will be reduced by when running. Cannot be set.
The amount stamina will increase by when resting. Cannot be set.
The player's base walk speed. Can be set.
The player's base run speed. Can be set.
The base max amount of stamina the player can naturally regenerate. Can be set.
The base amount stamina will be reduced by when running. Can be set.
The base amount stamina will increase by when resting. Can be set.
Returns if the player is currently squished. If it is set to true, the player will be squished for an infinite amount of time. Calling Unsquish or setting squished to false would be required to unsquish.
The direction the player is facing/their rotation on the y axis.
Functions:
- SetItem(itemId, slot)
- AddItem(itemId)
- GetItem(slot)
- RemoveItemSlot(slot)
- SetSlotCount(count)
- LockItemSlot(slot)
- UnlockItemSlot(slot)
- UseItem(itemId)
- HasItem(itemId)
- RemoveItemOfID(itemId)
- RemoveItem(slot)
- MakeGuilty(ruleBreak, time)
- GetGuilt()
- Squish(time)
- Unsquish()
- IsHidden()
- GetForward()
- AddStickerToInventory(stickerId, animation)
- GetInventoryStickers()
- GetActiveStickers()
- GetInventorySticker(slot)
- GetActiveSticker(slot)
- GetStickerValue(stickerId)
- ApplySticker(slot, stickerId)
This forcefully sets the item in the specified slot to be the item with the specified id.
This gives the item with the specified id to the player.
This returns the id of the item at the specified slot, "unknown" if it isn't an item included in the loader.
This removes the specified item slot from the inventory, reducing the total number of slots. This is the function used in the limited items challenge.
This sets the player's inventory to the specified amount of slots.
Locks the specified slot, preventing characters like Bully from stealing it.
Unlocks the specified slot, allowing characters like Bully from stealing it.
Simulates the player using the specified item. The player does not need to have the item in the inventory or have any slots available for this to work.
Returns true if the player has the item of the specified type.
Removes the first item found if it has the matching ID.
Removes the item at the specified slot.
Makes the player guilty of violating the specified rule for the specified time. Refer to the cheat sheet for valid vanilla rule breaks.
Returns the player's current guilt. Refer to the cheat sheet for vanilla rule breaks.
Squishes the player for the specified amount of time.
Unsquishes the player.
Returns true if the player is hidden.
Returns the player's forward vector.
Adds the specified sticker into the player's sticker inventory. animation is a bool that determines if the sticker opening animation plays.
Returns an array of the sticker ids in the player's inventory
Returns an array of the sticker ids that are active.
Returns the sticker at that slot in the sticker inventory
Returns the sticker at that slot in the active stickers list.
Returns the amount of the sticker with the specified id the player has active.
Sets the active slot to contain a sticker of the specified sticker id.
Cells, or also commonly referred to as tiles, are something you are probably already familiar with.
Variables:
- position - The cells grid position as an IntVector2.
- FloorWorldPosition - The Vector3 corresponding to the floor of the cell.
- CenterWorldPosition - The Vector3 corresponding to the center of the cell.
Functions:
- GetLight()
- GetRoom()
- SetLight(color, strength)
- PressAllButtons()
Returns the light for the cell, if it exists. Otherwise, returns nil.
Returns the room for the cell.
Creates or modifies the light at the cell, then returns the newly added or modified light. Can return nil.
Finds all buttons/levers/valves placed on that cell and attempts to press them.
A light lights up an area, determined by strength, with the color.
Variables:
- cell - The cell this light belongs to.
- color - The color of the light. Changing this will update the light.
- strength - The strength of the light. Changing this will update the light.
Functions:
- SetPower()
Sets the power to the specified state. Internally Plus keeps track of how many times the light has been turned off, so do not call this in a loop, or else the light will be unable to turn on.
A room has a set of textures, a function, and cells are assigned to it.
Variables:
- category - The category this room is (Class, Faculty, Office, Special, etc) as a string. Cannot be set.
- mapColor - The color of this room on the map. Changing this will update the map accordingly.
- powered - The rooms power state. If the room is powered off, then the activity will be as well. Can be changed.
- name - The name of the room, can be set in the editor. Can be changed.
- hasActivity - True if this room has an activity/notebook. Cannot be set.
- activityCompleted - True if this room has an activity/notebook and the activity is currently complete. Cannot be set.
Functions:
- GetCells()
- GetEntitySafeCells()
- GetLights()
- GetRandomEntitySafeCell()
- IsHall()
- GetZone()
- LockAllDoors()
- UnlockAllDoors()
- LockAllDoorsTimed(time)
- RespawnItem(itemId)
- RespawnActivity()
Returns all cells belonging to this room.
Returns the zone this room was assigned in the editor, with 0 being no zone.
Returns all entity safe cells belonging to this room.
Get all lights belonging to this room.
Returns a random entity safe cell that belongs to this room, defaulting to the first cell if not found.
Returns if this room is a hall.
Locks all doors connected to this room.
Unlocks all doors connected to this room.
Locks all doors connected to this room for the specified amount of time in seconds.
Selects a random item respawn point (a place where an item was or a Potential Item Spawn placed in the editor) and spawns the item of itemId there. If the room had a sticker pack in it, it is advised to avoid using this method.
Instantly causes the activity to become available again, increasing the notebook count by one.
The ElevatorManager is what manages almost everything regarding elevators and their current state.
Variables: This object has no variables
Functions:
- SetIntendedElevatorState(elevator, state)
- GetIntendedElevatorState(elevator)
- SetTotalOutOfOrderElevators(total)
- SetAllElevators(state)
- GetElevators()
Sets the intended state of the Elevator. Refer to the id cheat sheet for the state.
Gets the intended state of the Elevator.
Sets the amount of out of order elevators required. escapeSequenceActive must be true for this to work correctly.
Sets the state of all elevators to the passed in state. Refer to the id cheat sheet for the state.
Returns all elevators this ElevatorManager controls.
The elevator is an elevator/exit. It's state can be changed and gotten.
Variables:
- cell
- state
- powered
- gateIsOpen
The cell this elevator is on. Cannot be set.
The state this elevator is currently at. May not match ElevatorManager.GetIntendedElevatorState, refer to the id cheat sheet. Setting calls SetState
Whether or not this elevator is powered. Cannot be set.
Whether or not the gate for this elevator is currently open. Cannot be set.
Functions:
- SetState(state)
Sets the state of this elevator. Refer to the id cheat sheet.
An IntVector2 is used to represent a cell position. They can be added and subtracted from other IntVector2s.
Variables:
- x - The x position. Cannot be set.
- z - The z position. Cannot be set.
A Vector3 is usually used to represent a position. They can be added and subtracted from other Vector3s.
Variables:
- x - The x position. Cannot be set.
- y - The y position. Cannot be set.
- z - The z position. Cannot be set.
Functions:
- DistanceFrom(other)
This returns the distance from the Vector3 to "other".
A Color represents a well, color.
Variables:
- r - The r channel. Cannot be set.
- g - The g channel. Cannot be set.
- b - The b channel. Cannot be set.
Functions:
There are no functions for this type.