Start here: your first mod, no coding needed

This guide is for people who have never made a mod. You need no programming: everything here is done by copying folders and editing text files. At the end you will have a mod that changes a weapon's price and adds a brand-new sword that a merchant sells.

If BLSE is not installed yet, follow Installing first.

What you need#

• The game with the Unofficial Patch and BLSE installed.
• A text editor. Notepad works; Notepad++ is easier, because it shows line numbers and colours.
• The game's console, to test. Press ~ in the game. Type blse and press Enter: if BLSE answers with its version, everything is ready.

How BLSE mods work#

The game reads its data from text files: what an item costs and what it is called, what merchants sell, what characters say. Without BLSE you change these by replacing the game's files, and two mods that change the same file break each other.

With BLSE a mod is one folder. You put the folder in Bin/loader/blse/mods/, and the game sees the files inside it as if they were its own. You never touch the game's own files. To remove the mod, delete its folder.

A few words used in this guide:

Where to find the game's files#

The Unofficial Patch keeps readable copies of most data files in the game folder's Unofficial_Patch folder. Good places to look:

Only read and copy these files. Never edit them: your changes go in your mod folder.

Step 1: make the mod folder#

Create this folder (use your own name instead of my_first_mod: letters, digits and _):

Bin/loader/blse/mods/my_first_mod/

Optionally add a file mod.ini in it, so players see who made it:

[mod]
name = My First Mod
version = 1.0
author = Your name
description = A cheaper katana and a new sword at Mercurio's.

Start the game once. BLSE adds your folder to the list of mods in Bin/loader/blse/config/loadorder.txt. Type blse in the console: your mod is in the list.

Step 2: change an existing item (a cheaper katana)#

The katana's file is vdata/items/item_w_katana.txt. Open the copy in Unofficial_Patch/vdata/items/ to read it. Near the top you will find:

WeaponData
{
	"printname"	"Katana"
	...
	"item_worth"	"215"
	"player_sell"	"20"

item_worth is what a merchant asks, player_sell what a merchant pays you for it.

You could copy the whole file into your mod and change it, but then any other mod that changes the katana would fight with yours. Write a merge file instead: only the lines you change, in the same blocks. Create:

my_first_mod/blse/merge/vdata/items/item_w_katana.txt

with this text:

WeaponData
{
	"item_worth"	"100"
}

That is the whole file. BLSE takes the game's katana file, puts your value over the old one and gives the result to the game. Everything else about the katana stays as it was.

The rules for merge files in short:

• Use the same path as the game's file, but under blse/merge/.
• Repeat the block names (WeaponData { ... }) down to the value you change.
• A line "key" "value" sets that value. More you can do (add entries, remove them, pick one of several blocks with the same name) is in Mod folders.

Test it: start the game, load a save and visit a merchant who sells katanas. Merchants read prices when their trade screen opens; what you see also includes the game's haggling (your Persuasion), so it may be a little off 100.

Step 3: add a new item (a sword of your own)#

A new item needs three things: a name for it, an item file that describes it, and one line that tells BLSE which of the game's items it behaves like.

3a. Pick a class name. It must start with item_, use only lowercase letters, digits and _, and should contain your mod's name so it never clashes with someone else's: item_w_myfirstmod_sword. (w stands for weapon, as in the game's own names.)

3b. Tell BLSE what it behaves like. Create my_first_mod/blse/items.txt:

# <new item>              <behaves like this item of the game's>
item_w_myfirstmod_sword   item_w_katana

The second name is the template. Your sword fights the way a katana does: a melee weapon with its slashing attacks. Everything you can write in an item file (name, price, damage, models, sounds) comes from your own file.

3c. Write the item file. Copy Unofficial_Patch/vdata/items/item_w_katana.txt to

my_first_mod/vdata/items/item_w_myfirstmod_sword.txt

The file name must be the class name plus .txt. Then change what you like. The lines you will want first:

Lines starting with // are comments: the game ignores them.

3d. Try it. Start the game, load a save, open the console and type:

give item_w_myfirstmod_sword

The sword is in your inventory. If nothing happens, see When something does not work.

Step 4: sell it at a merchant#

What each merchant sells is in vdata/system/vendors.txt. Again you do not copy that file: you add your item with a merge file. Create

my_first_mod/blse/merge/vdata/system/vendors.txt

with this text:

VendorData
{
	Vendor
	{
		"@match"	"Name=Mercurio"
		+VendorItem
		{
			"Name"			"item_w_myfirstmod_sword"
			"InternalName"	"item_w_myfirstmod_sword"
			"AmmoOnly"		"0"
			"MinStage"		"0"
		}
	}
}

What each part means:

Test it: load a save, walk to Mercurio (Santa Monica) and open the trade screen. Your sword is in his list.

That's it: a complete mod with a changed item, a new item and a merchant selling it, without replacing a single game file.

When something does not work#

• The log: Bin/loader/blse/blse.log lists every mod BLSE loaded and every problem it found, with the file and the mod's name: a merge it could not read, an item whose file is missing, two mods changing the same thing. Search it for your mod's name.
• See what the game got: BLSE writes every merged file to Bin/loader/blse/cache/files/. Open, for example, cache/files/vdata/system/vendors.txt to check that your item is in Mercurio's list.
• Typing errors cause most problems: a missing " or }, a class name spelled differently in items.txt, the item file's name and the merge. Copy and paste names rather than retyping them.
• The console's blse command lists your mod and says why it is switched off, if it is.

Before you share your mod#

• Zip it starting with Bin (Bin/loader/blse/mods/my_first_mod/...), so players extract it into the game folder and are done. See packing your mod.
• Tell players to keep it installed while they play a game they started with it. A save that holds an item your mod added cannot be loaded without the mod: the game crashes when it tries. Say this on your mod's page.
• Keep your class names once you have released the mod: renaming an item, or changing its template in items.txt, breaks players' saves that hold it.
• Need another mod? Name it in mod.ini (requires = other_mod_folder), and BLSE switches your mod off with a clear message if it is missing. See mod.ini.

What next#

You can do much more with folders and text files alone:

When you want things to happen (react when the player enters a level, kills someone, picks something up; show text on screen; add console commands), you need a small Python script. Getting started with Python mods starts from zero.

A complete example mod folder is examples/mods/blse_sample (in the release zip: SDK/examples/mods/blse_sample).