Set a Light Item Off by Default

There’s a lot of lighting options in BG3. A useful type is a light item, be this a candle, chandelier, sconce, or any number of other things. However, when you place these items in the world, almost all of them are lit up by default. Sometimes we want them to be off when the player finds them.

How a Light Turns On and Off

Let’s take the case of a candle for the rest of this guide:

light candle

Its root template is called CINE_LTS_DUN_Candles_Cluster_B, and is an item. Recall items are interactable. This means a player can click on them to do something - in this case light the candle, and snuff it out. This interaction is handled by a behaviour script, one of the Divinity Engine’s many scripting languages. The script for this candle can be found in the sidebar

light sidebar

If we open the script editor, we can find the file with this script in it.

In the BG3 Modding Toolkit, files starting with DOS2_ are truncated in some editors.
light script

Exactly what this file does is a topic for another time, but there are a few lines that are important to note.

#INCLUDE BurningItem

INIT
	USING BurningItem (1)

	ITEM:__Me
	EXTERN INT:%StartLit = 0 (2)
	INT:%IsStatusOn
	EXTERN STRING:%LightSourceOnSound = "DEC_Interactive_Lightsources_Torch_Small_On"
	EXTERN STRING:%LightSourceOffSound = "DEC_Interactive_Lightsources_Torch_Small_Off"

	EXTERN INT:%AllowUserInteraction = 1
...
EVENT InitTorch
ON
	OnInit()
ACTIONS
	SetStatusVisualEnabled(__Me,"BURNING",INT:0)
	IF "c1&!c2"
		IsEqual(%StartLit,1) (3)
		ItemHasStatus(__Me,BURNING)
	THEN
		ItemApplyStatus(__Me,BURNING)
		Set(%StartLit,0)
		IF "c1"
			GetVar(%IsStatusOn,__Me,"IsStatusOn")
		THEN
			SetVar(__Me,"IsStatusOn",INT:1)
		ENDIF
1 This script imports variables and functions from another. If you’re familiar with Python, this is like an object inheriting from a base class.
2 This variable determines if the candle starts lit or not. Notice the EXTERN. This means the variable is exposed when the script is assigned to an object.
3 The logic that turns the candle on or off based on the StartLit variable.

Setting the StartLit Variable

Now we know how the candle’s scripting works, we can set our object to be unlit by default.

  1. Open the Sidebar and scroll down to Scripts

  2. Double click DOS2_Torch in the assigned scripts column.

  3. Edit the exposed StartLit variable. 1 is on, 0 is off.

  4. Click OK.

light edit script

The candle has been updated! You may need to reload the level to see the effects.

This change will not set all candles off by default, just this one object. If you want all your light sources to be off, you will have to do this for every item.