On this page 4 sections
BLSE is in beta, but its API is stable: later versions only add to it, so mods made for one version keep working with later ones. Each page notes the version a feature appeared in where that matters.
Where to start#
| You want to | Start with |
|---|---|
| See everything BLSE can do | Features |
| Install BLSE or mods that need it | Installing and troubleshooting |
| Know where a mod's files go (scripts, plugins, mod folders, settings) | Where mod files go |
| Make your first mod, without any programming | Start here: your first mod: a step-by-step guide that changes an item, adds a new sword and puts it in a shop |
| Make things happen in the game (react to events, show text, add commands) | Getting started with Python mods: starts from zero, no Python knowledge needed |
| Write native C++ plugins | Plugins: getting started (for programmers) |
Every mod is one folder in Bin/loader/blse/mods. It can hold three kinds of things, and one mod can mix them:
- Game files and small text files: no code. New and changed items, merchants, dialogue lines, quests, map changes, models, textures and sounds. Mod folders
- Python scripts:
.pytext files that react to what happens in the game. Most mods that need logic are scripts. - Native plugins: compiled C++ DLLs, for programmers who need speed or to change the game's own code.
Python mods#
Python mods are .py files (the game's Python 2.1) in a mod folder's blse/scripts, which BLSE runs at game start. This is the easiest way to make a mod that does things.
| Page | Covers |
|---|---|
| Getting started | Your first mod, how scripts are loaded, the basic functions, console commands |
| Events | Level, frame, save and load events, entity outputs, gameplay and combat events, entities appearing and disappearing, what the player looks at, character creation |
| Dialogue | Reading dialogue, hiding replies, changing texts, new conversations, replies and journal quests from mods |
| Items and inventories | Inventory events, item data, giving, removing, dropping and equipping items, new items and weapons |
| Combat, damage, stats and Disciplines | Damage rules, stat changes, Disciplines (blocking, cost), kills, pushes, the game's Python errors |
| The world | Spawning and teleporting entities, inventories of any character, finding entities, console variables, frame rate, camera, sounds |
| NPC AI | Relationships and enemies, schedules, moving and following, senses, why an NPC does not fire |
| Models and appearance | Scaling models and single bones, faces, skins, body groups, colour, materials, outfits for the player |
| Animation | A model's sequences, playing one on any NPC, the current animation, start and end events, rules for an activity, new animations for the game's models, swinging bones |
| Companions | NPCs that go with the player through level changes and fight beside them |
| Saved data, settings and translations | Save-game data, values on entities, the shared database, JSON, .ini settings, translated text |
| Interface: text and the HUD overlay | On-screen text; text, boxes, images, shapes and text fields drawn over the game |
| Screens and windows | The game's own screens: reading, restyling and adding to them; mods' windows, button sounds, blocked screens |
| Keys and the mouse | Key and control state, blocking and pressing keys, the mouse cursor in play |
| Mod folders | Mods as folders of game files, the load order (config/loadorder.txt), merging data files, changing a map's entities, new items and animations without code |
Native plugins#
Plugins are 32-bit DLLs that use the C API in include/blse_api.h. Use one when you need speed, your own threads or direct hooks into game code.
| Page | Covers |
|---|---|
| Getting started | The plugin contract, plugin information, the host API, messaging, building, examples |
| Events, filters and game rules | Events, character creation, damage and Discipline filters, stat changes, dialogue, keys |
| The world, saved data and settings | Save-game data, settings, world functions, NPC AI, animation, models and appearance, player outfits, camera, sound |
| Interface | On-screen text, game screens, the HUD overlay, translated text |
| Drawing with Direct3D 9 | Draw callbacks before and after the HUD overlay, the game's device, device loss (b0.5.49) |
| Hooks and crash reports | Hooking game code through BLSE, plugin crashes, reading a crash log |
| Working with the game's Python | Calling the game's scripting from a plugin, adding Python functions, console commands |
| Conversations | Conversations and replies from plugins |
The header include/blse_api.h is the contract: its comments describe every function, field and message payload. The release zip ships it in the SDK folder with example plugins.
Python or a plugin?#
Most mods need only Python: it covers most of what the plugin API does; plugins add hooking game code directly, running your own threads and native speed. Python mods and plugins share one message bus, console commands, the shared database and entity values, so a plugin can add a function that a Python mod then calls.