Features

Everything BLSE gives mods, by area. How to use each part: Python mods, native plugins, mod folders.

Mods and how they load#

Python mods. A mod's .py files, in its mod folder's blse/scripts, run at game start, without editing any game file. Bloodlines already runs its own scripts in Python, but there's nowhere to add yours: modding it means replacing game files, and scripts only run when a map, a dialogue line or the engine calls one of the game's own script functions. BLSE gives that same Python a mod folder, plus events (deaths, damage, items, quests, level changes, key presses) and functions that reach what the game's scripts can't (damage rules, Disciplines, dialogue, NPC AI, spawning, on-screen UI). Mods can add their own console commands, and a script that fails is logged without stopping the others.

Native plugins. 32-bit DLLs in a mod folder's blse/plugins, with a name, a version and dependencies on other plugins, for mods that need the speed or reach of C++. A BLSE plugin is a DLL, like any .vtm, but you don't have to find the game's code, hook it by hand or build everything from scratch. BLSE gives plugins the same events and functions as Python mods, a shared message system so plugins and Python mods can work together, and a hook system that checks the game's code first and refuses patches that would overlap another mod's. If a plugin crashes while BLSE is calling it, BLSE disables that plugin and logs which one it was, so the game can usually continue. Crashes elsewhere (a plugin's own threads, or code it patched itself) can still crash the game, and then the crash log names the plugin.

Mod folders. A mod is one folder in Bin/loader/blse/mods. Its game files (models, materials, sounds, maps, dialogue, data) are found by the game as if they were its own, without replacing anything in the game folder. Several mods can change the same file at once:

• Merge files add to the game's data files (quests, items, merchants' stock, character creation, stats) instead of replacing them, key by key.
• Dialogue lines can be merged line by line, and plain text files can be extended at the start or end.
• Map patches add, remove or change a map's entities when it loads.
• config/loadorder.txt sets the load order (a later mod wins), mod.ini gives a mod its name and version, and a mod folder can also carry its own Python modules, BLSE scripts and native plugins.
• BLSE refuses changes that would break the game, such as a stats.txt with a different number of Disciplines, and says why in the log.

Cooperation between mods. Python mods and plugins publish and subscribe to the same messages. Rules from several mods (damage, Disciplines, dialogue, animation) are combined in a fixed, documented order, and conflicts between mod folders are listed in the log.

Events#

• Level and frame events – level changes (and where the next one goes), every frame, game saved, loaded, load failed, new game, engine restart.
• Entity outputs – every output a game entity fires (OnDeath, OnTrigger, ...), with who caused it.
• Combat – attacks, damage, kills, pushes, combat and stealth state changes, each NPC's fight.
• Gameplay – quests, dialogue lines and choices, Discipline use, stat changes, items picked up, given, equipped and used, entities appearing and disappearing, what the player is looking at or using.
• Character creation – each questionnaire screen and answer, the clan, gender, history and points chosen, and the finished character.
• Animation – an animation starting and ending on any character.
• Input and screens – keys, mouse buttons and the game's controls (whatever key they are bound to), game screens and menus opening and closing, console variable changes.

Changing the game#

• Damage – change, scale or cancel damage before it lands, by attacker, victim, weapon or damage type.
• Disciplines – block a Discipline for the player, a kind of NPC or one character, or change what it costs.
• Dialogue – hide replies, rewrite lines, read the conditions of a conversation. Add whole new conversations, and replies under the game's own lines, side by side with other mods, with Python functions as conditions and actions. Journal quests are added by merging the game's quest files.
• Entity inputs – block or change the inputs sent to entities (doors, buttons, scripted sequences).
• Items – read and change names, descriptions, prices and weights; give, remove, drop, move and equip items for the player, NPCs and containers.
• NPC AI – set relationships and enemies, start schedules, send NPCs to a place or have them follow, freeze them in place, set sight and hearing, calm or provoke them.
• Spawning and teleporting – create entities, move any entity, change its keyvalues (rename an NPC, give it a conversation).
• Character creation – change which clans can be chosen, or what a clan becomes.
• Camera and sound – field of view, camera position and view, play and stop sounds and UI sounds.
• Console variables – read and set the game's settings, and be told when they change.

New content#

• New items and weapons – a new item behaves like one of the game's items (a katana, a pistol, a blood pack, a key) but has its own data: name, description, models, pictures, price, damage, magazine and sounds. It works everywhere the game creates items: maps, merchants, the console's give, saves. Mods without code list their items in a text file (blse/items.txt) next to each item's data file.
• New conversations and quests – see Dialogue above; several mods can add to the same NPC.
• New animations – animation files are added to the game's models when they load, without editing any model. The new animations come after the game's own, so saves and the game's animations keep working, and several mods can add to the same model. A mod can also replace an animation by name.
• Companions – an NPC goes with the player through level changes with its whole state, follows, fights beside the player and waits when told.

Characters and animation#

• Models – scale whole models, and scale, move and turn single bones.
• Faces – hold facial expressions.
• Looks – change skins, body groups, tint and transparency, and give one character other materials. Optionally kept in the save.
• Player outfits – clothes for the player from a mod's outfits.txt or a script, worn whatever armor is on (the armor keeps its protection). They stay through weapon changes, first and third person and saves, and a save still loads if the outfit's mod is removed.
• Animation – list a model's animations, play any of them on any NPC (once, looping or held), read what a character is playing, and set rules that change which animation the game picks for an activity.

Interface#

• On-screen text – messages in the middle or top of the screen, or in the console.
• HUD overlay – text, boxes, images, shapes, clickable elements and text fields drawn over the game, optionally also over its menus, with your own fonts.
• The game's own screens – read, restyle and add to the game's panels: labels, buttons, images, text fields, checkboxes, sliders, drop-downs, progress bars and scrolling lists.
• Windows and replaced screens – a mod can open its own windows, or keep a game screen from opening and show its own.
• Button sounds – give any button of the game's menus its own hover, press and click sounds.
• Direct3D drawing – native plugins can draw with the game's own Direct3D 9 device, under or over BLSE's overlay: blurred backgrounds, glow, custom shapes. Works with the game's normal renderer and with DXVK.
• Keys and mouse – read keys and controls, block keys, press keys for the player, show a mouse cursor in play.

Data#

• Save-game data – values mods keep inside the save game.
• Values on entities – named values attached to any NPC or object, saved with the game and shared between mods.
• Shared database – one structured document, saved with the game, that Python mods and plugins both read and write.
• Settings files – .ini files in Bin/loader/blse/config that players can edit.
• JSON files – structured data files shared by every save.
• Translations – text for each language, chosen from the player's Windows language.

Robustness#

• Crash reports – the game's own crash log gets a BLSE section saying which mod was running, and crashes the game does not report get a BLSE log with a minidump. Both say what the registers and the stack point to.
• Plugin isolation – a plugin that crashes inside BLSE's code is disabled instead of taking the game down.
• Build identification – BLSE checks the game's files before touching its code, and each feature that needs the game's code checks it again before it hooks.
• Light when unused – the bigger features install their hooks only when a mod first uses them, and the rest do no more than a quick check, so BLSE with no mods costs the game almost nothing.
• Leak check – the console command blse_debug shows the game's memory and what BLSE holds, to compare across loads.