The War In Rapture

BioShock Remastered — Comprehensive Game Modification Tool

Overview

The War In Rapture is a comprehensive mod manager for BioShock Remastered that provides granular control over enemy spawns, weapon balance, enemy health, loot tables, and plasmid costs — all through a graphical interface.

This tool is designed to be educational and deconstructible. If you're interested in learning how BioShock modding works, understanding Unreal Engine 2.5 package formats, or building your own game modification tools, this repository serves as a complete reference implementation.

What This Mod Does

The mod modifies BioShock Remastered by patching two types of game files:

INI Config Files — Text-based balance settings packed inside ConfigINI.IBF. We extract them, modify values, and write loose copies that the engine loads in place of the archive.
BSM Map Files — Binary Unreal Engine packages (.bsm) containing level geometry, actors, and Kismet scripting. We binary-patch these to duplicate spawner actors and inject additional scripted encounter spawns.

Features

Tab 1 — Encounters (Scripted Spawns)

Per-encounter spawn multipliers with hierarchy: Global > Level > Encounter
Add custom enemies to any scripted encounter
Choose from any AI type available in that map (Splicers, Bouncers, Rosies, Houdini, Spider, Nitro, etc.)
Level-specific control over story fights and ambushes

Tab 2 — Repopulation

Respawn speed multiplier — divides the repopulation timer (higher = faster respawns)
Spawner duplication — clones AggressorSpawner/ProtectorSpawner actors in map files
Per-level control over maximum simultaneous enemy counts
Security bot spawner support

Tab 3 — Weapons

Adjust base stats: Magazine Size, Fire Rate, Reload Rate (per weapon)
Ammo damage values via StimuliSets (per ammo type)
Ammo max carry capacity
Weapon rework presets (Electro Rage, Hellfire, Igniting Cyclone, etc.)

Tab 4 — Enemies

Base health values per enemy type
Health, Max Health, Frozen Health adjustments
Global scaling across all levels

Tab 5 — Loot

Edit per-deck loot tables for each enemy category
Change drop items (dropdown with all game items)
Adjust drop chance percentage
Set min/max stack sizes
Add new entries or remove existing ones
Scale all drop chances with a multiplier

Tab 6 — Plasmids

Adjust ADAM costs for all plasmids and gene tonics
Plasmid rework system with configurable effects

Tab 7 — Vending

Circus of Values price multiplier
Ammo Bandito price multiplier

How to Use

Quick Start

Run the mod manager:
```
python war_in_rapture.py
```
Adjust settings across all tabs to your preference.
Click "Apply Mod" — the tool backs up originals, then patches everything.
Launch BioShock Remastered and start a new game (or load from a level transition point for scripted spawn changes to take effect).
Click "Restore All" at any time to revert to vanilla.

Detailed Tab Guide

SPAWNS Tab

Repopulation Settings (INI):

Controls how fast enemies respawn in cleared areas
The "Respawn Speed" multiplier divides the repopulation timer
Higher multiplier = faster respawns

Repopulation Spawners (per level):

Duplicates placed AggressorSpawner/ProtectorSpawner actors in the map file
Each spawner is one spawn point
Multiplying them increases the maximum number of enemies that can exist in an area simultaneously

Scripted Encounters (per level):

One-time spawns triggered by entering areas or story events (ambushes, story fights)
Use "+ Add Spawn" to add extra enemies to any encounter
Choose from any AI type available in that map

WEAPONS Tab

Adjust player weapon base stats
Magazine Size, Fire Rate, Reload Rate (per weapon)
Ammo damage values (per ammo type, via StimuliSets)
Ammo max carry capacity

ENEMIES Tab

Adjust base health values per enemy type
Health, Max Health, Frozen Health
Affects all levels globally

LOOT Tab

Edit per-deck loot tables for each enemy category
Change what item drops (dropdown with all game items)
Adjust drop chance percentage
Set min/max stack sizes
Add new entries or remove existing ones
Scale all drop chances with a multiplier

PLASMIDS Tab

Adjust ADAM costs for all plasmids and gene tonics

Technical Deep Dive

This section is for modders and developers who want to understand how BioShock modding works at a technical level. The War In Rapture serves as a complete reference implementation.

BioShock File Formats

IBF Archive Format

BioShock Remastered stores configuration files in a custom archive format called .ibf (likely "Info Binary Format"). The main config archive is ConfigINI.IBF (~2.1 MB) containing all game balance INI files.

Archive Structure:

Header with file count and offset table
Compressed file data blocks
File entries with names, sizes, and offsets

Our ibf_extract.py tool can extract these archives. The game engine checks for loose INI files in ContentBaked/pc/System/ first before falling back to the archive — this is how we apply mods without touching the original files.

BSM Package Format (Unreal Engine 2.5)

Map files use the .bsm extension (BioShock Map) but are standard Unreal Engine 2.5 packages. The format is documented in the bsm_parser.py module.

Package Structure:

Header (64 bytes):
- Signature (0x9E2A83C3)
- Package version (142 for BioShock Remastered)
- Name table offset/count
- Import table offset/count
- Export table offset/count

Name Table:
- String entries with length and null terminator
- Used for all object names, property names, etc.

Import Table:
- References to objects in other packages
- Class package, class name, outer package, object name

Export Table:
- Local object definitions
- Class reference, super reference, object name
- Serial data offset and size
- Flags and other metadata

Serial Data:
- Actual object data (properties, arrays, structs)
- Variable-length depending on object type

Class Index (CI) System:

Compact integer references to name table entries
1 byte for indices < 256, 2 bytes for < 65536, etc.
Used throughout the file format to save space

Our bsm_parser.py module implements a full reader/writer for this format, allowing us to parse, modify, and rewrite BSM files while maintaining structural integrity.

The INI Patching System

INI Parser Design

The ini_config.py module implements a custom INI parser designed for round-trip modification:

# Preserves comments, whitespace, and ordering
entries = [
    {'section': 'Section1', 'key': None, 'value': None, 'raw': '; Comment\n'},
    {'section': 'Section1', 'key': 'Prop', 'value': '123', 'raw': 'Prop=123\n'},
    # ...
]

Key Design Decisions:

Raw line preservation — Comments and formatting are maintained exactly
Ordered entries — Not nested dicts, so we handle duplicate keys (e.g., multiple LootSpec= per section)
Section-based operations — Easy to find/modify values by section and key
Round-trip safe — Write back exactly what we read, with only intended changes

INI Files Modified

Weapons.ini (~150 KB):

Weapon base stats (magazine, fire rate, reload)
Ammo damage via StimuliSets (damage type definitions)
Plasmid and weapon effect configurations

Ai.ini (~80 KB):

Enemy health values per AI class
Per-deck variants (Deck1, Deck2, etc.)
Damage multipliers and combat stats

LootTables.ini (~500 KB):

Per-deck loot tables for each enemy category
Item drop chances and stack sizes
Vending machine loot specifications

Spawning.ini (~30 KB):

Repopulation timers and spawn caps
Engagement distances and AI behavior parameters
Adaptive difficulty triggers

Difficulty.ini (~20 KB):

Adaptive difficulty thresholds
Spawn rate triggers based on player performance

Plasmids.ini (~25 KB):

Plasmid and gene tonic ADAM costs
Plasmid effect configurations

Loot Table Rebuilding

The loot table system supports full rebuild (add/remove entries) via rebuild_loot_table():

def rebuild_loot_table(entries, section, loot_specs):
    """Rebuild a loot table section with new LootSpec entries."""
    # Remove existing LootSpec lines
    # Add new entries from loot_specs list
    # Preserve other properties (DropChance, etc.)

A comprehensive LOOT_ITEMS registry maps engine class paths to friendly display names for the UI dropdowns.

The BSM Binary Patcher

The BSM patching system is the most complex part of the mod. It allows us to modify compiled Unreal packages without access to the original source code.

Spawner Duplication

The bsm_spawn_patcher.py module handles duplicating repopulation spawners:

Process:

Parse the BSM package (name table, import table, export table)
Find all AggressorSpawner and ProtectorSpawner exports
Clone each spawner's export entry and serial data with offset positions
Append clones to the package and rewrite the header

Key Challenges:

Offset recalculation — All serial offsets must be updated after insertion
Name table extension — New names added for cloned objects
Header rewriting — Counts and offsets updated in package header
Cross-reference integrity — Internal references must remain valid

Scripted Encounter Modification

The bsm_script_patcher.py module handles adding spawns to scripted encounters:

Kismet Script System:

BioShock uses Unreal's Kismet visual scripting system
Scripts are stored as sequences of Actions in the BSM
ActionSpawnAI is the specific action type for spawning enemies

Process:

Parse the BSM package and identify Script/ActionSpawnAI relationships
For each encounter with additions, clone ActionSpawnAI exports
Optionally patch the AITypeToSpawn reference for different enemy types
Extend the parent Script's Actions array to include cloned actions
Rewrite the package with updated headers and appended data

Array Extension:

# Script Actions array format
# Array flag + element count + element indices
# We append new action indices and update the count

Spawn System Architecture

BioShock's spawn system has two main components:

1. Repopulation System

Spawner actors placed in the map (AggressorSpawner, ProtectorSpawner)
Each spawner can spawn multiple enemies over time
Spawn caps limit maximum simultaneous enemies
Repopulation timers control spawn frequency
Engagement distances determine when spawners activate

Our mod duplicates spawner actors to increase spawn capacity:

Original: 1 AggressorSpawner → spawns up to 3 enemies
Modified: 3 AggressorSpawner → spawns up to 9 enemies

2. Scripted Encounter System

Kismet scripts trigger one-time spawns
Story events, area triggers, ambushes
ActionSpawnAI actions spawn specific enemy types
Scripts are saved in game state, so changes require level reload

Our mod adds extra ActionSpawnAI actions to existing scripts:

Original Script: [SpawnSplicer, SpawnSplicer]
Modified Script: [SpawnSplicer, SpawnSplicer, SpawnBouncer, SpawnBouncer]

Hierarchy System

The mod implements a multiplier hierarchy:

Global Multiplier (applies to all levels)
    ↓
Level Multiplier (overrides global for specific level)
    ↓
Encounter Multiplier (overrides level for specific encounter)

This allows fine-grained control without editing every single encounter.

File Structure

TheWarInRapture/
├── war_in_rapture.py          # Main launcher — graphical mod manager UI
├── README.md                  # This file
├── README.txt                 # Original brief documentation
├── settings.json              # User settings (game path, etc.)
│
├── core/                      # Core engine modules
│   ├── __init__.py            # Package init with module descriptions
│   ├── bsm_parser.py          # Unreal package (.bsm) binary format reader/writer
│   ├── bsm_spawn_patcher.py   # Repopulation spawner duplication in map files
│   ├── bsm_script_patcher.py  # Scripted encounter spawn additions in map files
│   ├── ini_config.py          # INI file parser, patcher, and game balance config
│   ├── bioshock_spawn_mod.py  # IBF archive extraction and spawn INI tuning
│   ├── encounter_order.py     # Encounter ordering and metadata
│   └── bsm_parser.py          # BSM binary format utilities
│
├── tools/                     # Development and debugging utilities
│   ├── ibf_extract.py         # Standalone IBF archive extractor
│   ├── parse_bsm.py           # Standalone BSM file inspector
│   ├── find_spawn_props.py    # Search BSM files for spawn-related properties
│   ├── bsm_spawn_scanner.py   # Scan maps for all spawn-related actors
│   └── dump_inis.py           # Dump all INI files from ConfigINI.IBF to disk
│
├── presets/                   # Pre-configured mod presets
│   ├── The War In Rapture x5.json
│   ├── The War In Rapture x10.json
│   ├── 10x Spawn Rate ONLY preset.json
│   └── 10x Spawn Rate ~ Vending Changes ~ Weapon Changes ~.json
│
├── images/                    # UI assets
│   └── War In Rapture Logo.png
│
└── backups/                   # Auto-generated backup directory
    ├── pristine/              # Unmodified copies of all game files
    ├── maps/                  # Pre-patch map backups (repopulation spawners)
    └── maps_scripts/          # Pre-patch map backups (scripted encounters)

Educational Resources

This repository is designed to be educational. Here's how to learn from it:

For Beginning Modders

Start with ini_config.py — The INI system is the easiest to understand
- Read the parser functions to see how INI files are structured
- Look at the patch functions to see how game values are modified
- Try adding your own simple INI patches
Explore the tools directory — Standalone scripts for inspection
- dump_inis.py — Extract and examine game config files
- parse_bsm.py — Inspect BSM package structure
- ibf_extract.py — Understand the IBF archive format

For Advanced Modders

Study bsm_parser.py — Complete Unreal package format implementation
- Understand the header, name table, import/export tables
- Learn the Class Index (CI) system for space optimization
- See how serial data is parsed and written
Examine bsm_spawn_patcher.py — Binary modification techniques
- How to clone objects while maintaining integrity
- Offset recalculation strategies
- Name table and header updating
Read bsm_script_patcher.py — Kismet script modification
- How Kismet scripts are stored in BSM files
- Array extension techniques
- Cross-reference patching

For Tool Developers

UI Architecture — war_in_rapture.py
- Tkinter-based tabbed interface
- Threading for long operations
- Settings persistence
- Preset system
Pipeline Design — The apply process
- Clean slate restoration from pristine backups
- Sequential patching stages
- Error handling and rollback

Key Concepts to Research

Unreal Engine 2.5 — The engine BioShock Remastered uses
Kismet — Unreal's visual scripting system
Package format — How Unreal stores compiled game data
INI configuration — Text-based game balance systems
Binary patching — Modifying compiled files without source

Requirements

Python 3.8+ — The mod manager is written in Python
BioShock Remastered — Steam, GOG, or Epic Games version
Windows — The tool is designed for Windows (BioShock is Windows-only)
~500 MB free disk space — For backups and patched files

Game Path Detection

The tool automatically detects BioShock Remastered in common locations:

Steam: C:\Program Files (x86)\Steam\steamapps\common\BioShock Remastered
GOG: C:\GOG Games\BioShock Remastered
Epic: C:\Program Files\Epic Games\BioShock Remastered
And other common Steam library locations (D:, E:, F:, G:, X: drives)

If auto-detection fails, you can manually set the path in settings.json.

Installation

Option 1: Clone from GitHub

git clone https://github.com/NykoDesigns/The-War-In-Rapture.git
cd The-War-In-Rapture/TheWarInRapture
python war_in_rapture.py

Option 2: Download Release

Download the latest release from GitHub
Extract the zip file
Run war_in_rapture.py

First Run

On first run, the tool will:

Detect your BioShock Remastered installation
Create pristine backups of all game files (takes ~5 minutes)
Create the backups/ directory structure
Save your game path to settings.json

Do not interrupt the first run backup process — it needs to complete once to establish a clean baseline.

Usage Guide

Applying the Mod

Launch the tool: python war_in_rapture.py
Navigate tabs and adjust settings to your preference
Click "Apply Mod" — The tool will:
- Restore pristine files (clean slate)
- Patch INI files
- Duplicate repopulation spawners
- Add scripted spawns
- Apply all changes
Launch BioShock Remastered and play

Restoring Vanilla

Click the "Restore All" button to revert all changes:

Copies pristine backups back to game directory
Removes loose INI files
Renames ConfigINI.IBF.bak back to ConfigINI.IBF

Saving/Loading Presets

Use the "Save Preset" and "Load Preset" buttons to:

Save your current configuration to a JSON file
Load previously saved configurations
Share presets with others

Important Notes

Scripted encounter changes require a fresh level load (new game or level transition). Loading a save mid-level uses the saved Script state.
Repopulation and INI changes take effect immediately on game launch.
Always patch from pristine originals — the tool prevents compounding changes.
Backups are automatic — pristine copies are created on first run.

Troubleshooting

"Game path not found"

Ensure BioShock Remastered is installed
Check common installation locations

Manually edit settings.json to set the correct path:

{
  "game_root": "X:\\Your\\Path\\To\\BioShock Remastered"
}

"Failed to patch BSM file"

Ensure the game files are not read-only
Check that you have write permissions
Verify the BSM file is not corrupted (run validate_files in Steam)
Try restoring from pristine backups and reapplying

"Changes not appearing in game"

For scripted spawns: Start a new game or transition between levels
For INI changes: Restart the game completely
Check that ConfigINI.IBF was renamed to .bak
Verify loose INI files exist in ContentBaked/pc/System/

Tool crashes on startup

Ensure Python 3.8+ is installed
Check that all core modules are present
Try running from command line to see error message
Check settings.json for corruption (delete it to regenerate)

Performance issues

High spawn multipliers (10x+) can impact performance
Reduce scripted spawn additions in large levels
Lower repopulation speed if experiencing lag
Consider using the 5x preset instead of 10x

Contributing

This is an open-source educational project. Contributions are welcome in the form of:

Bug fixes — Report issues with detailed reproduction steps
Documentation — Improve this README or add code comments
New features — Implement additional modding capabilities
Tools — Add new utilities to the tools directory
Presets — Share interesting configuration presets

Development Guidelines

Preserve the educational nature — Keep code well-commented
Maintain backward compatibility — Don't break existing presets
Test thoroughly — Verify changes work on clean installations
Document changes — Update README and code comments
Follow existing style — Match the codebase formatting

Submitting Changes

Fork the repository
Create a feature branch
Make your changes
Test thoroughly
Submit a pull request with detailed description

Technical Architecture

The Patching Pipeline

When you click "Apply Mod", the following steps execute:

Step 1 — Restore Pristine Maps

All .bsm map files are restored from backups/pristine/
Ensures we always patch from a clean base (prevents double-patching)

Step 2 — Patch INI Files

Extract all .ini files from the pristine ConfigINI.IBF backup
Parse each into structured entries (preserving comments/formatting)
Apply modifications:
- Spawning.ini: Reduce repopulation timers, increase spawn caps
- Difficulty.ini: Lower adaptive difficulty thresholds
- Weapons.ini: Patch weapon stats and ammo damage StimuliSets
- Ai.ini: Patch enemy Health/MaxHealth/MaxFrozenHealth
- LootTables.ini: Rebuild loot tables with modified/added/removed specs
- Plasmids.ini: Patch CreditValue (ADAM cost) per plasmid
Write all .ini files to ContentBaked/pc/System/
Rename ConfigINI.IBF -> .bak so the engine loads our loose files

Step 3 — Duplicate Repopulation Spawners

For each map with a spawner multiplier > 1:
- Parse the BSM package (name table, import table, export table)
- Find all AggressorSpawner and ProtectorSpawner exports
- Clone each spawner's export entry and serial data with offset positions
- Append clones to the package and rewrite the header

Step 4 — Add Scripted Spawns

For each map with spawn additions:
- Parse the BSM package and identify Script/ActionSpawnAI relationships
- For each encounter with additions, clone ActionSpawnAI exports
- Optionally patch the AITypeToSpawn reference for different enemy types
- Extend the parent Script's Actions array to include cloned actions
- Rewrite the package with updated headers and appended data

Step 5 — Done!

The game will load patched files on next launch

Error Handling

The tool includes comprehensive error handling:

Pre-patch validation — Checks file integrity before modification
Rollback on failure — Restores backups if patching fails
Detailed error messages — Helps diagnose issues
Safe defaults — Won't apply partial changes

Thread Safety

Long operations run in background threads:

BSM parsing and patching (can take 30+ seconds)
INI extraction and writing
File copying operations

The UI remains responsive during these operations with progress indicators.

Advanced Topics

Binary Analysis

The repository includes several binary analysis tools:

_parse_shockgame_u.py

Parses the ShockGame.U package (compiled Unreal classes)
Used to investigate plasmid ability classes
Demonstrates package format analysis

_scan_cut_content.py

Scans game files for cut/unused content
Finds commented-out sections in INI files
Documents cut plasmids, weapons, and features

_test_teleport_fix.py

Tests the Teleport plasmid restoration
Demonstrates class name mismatch debugging
Shows how to fix binary-level issues

Modding Techniques Demonstrated

INI Patching — Text-based configuration modification
Binary Package Patching — Modifying compiled Unreal packages
Archive Extraction/Injection — Working with IBF archives
Spawn System Modification — Understanding and modifying game spawns
Loot Table Rebuilding — Complete table reconstruction
Kismet Script Modification — Visual scripting system editing
Cross-Reference Patching — Maintaining integrity in binary files
Name Table Extension — Adding new names to packages
Array Extension — Growing data structures in binary files
Offset Recalculation — Maintaining file structure after modification

Reverse Engineering Insights

This repository documents several reverse engineering findings:

MomentumScale System — Only works for weapon damage, not plasmids
Sonic Boom Push — Hardcoded in compiled AirBlast ability class
Teleport Plasmid — Cut content with class name mismatch (Teleportation vs Teleport)
Chain Lightning — Abandoned due to class hierarchy constraints
Cut Content — 15+ ecology plasmids, various weapons/ammo types

These findings are documented in the code and can serve as reference for other modders.

License

This project is provided as-is for educational purposes. The code is open-source under the MIT License.

Important: This mod modifies game files. Always backup your game installation before using any mod. The authors are not responsible for any issues that arise from using this tool.

Credits

Developed by: NykoDesigns

Special Thanks:

The BioShock modding community
Unreal Engine documentation
Everyone who contributed to understanding BioShock's file formats

Disclaimer

This tool is for educational purposes only. It modifies BioShock Remastered game files and may:

Break game updates
Cause instability
Affect multiplayer (if applicable)
Violate terms of service (use at your own risk)

Always backup your game files before applying mods. The authors assume no responsibility for any damage or issues caused by this tool.

Support

For issues, questions, or contributions:

GitHub Issues: https://github.com/NykoDesigns/The-War-In-Rapture/issues
GitHub Discussions: https://github.com/NykoDesigns/The-War-In-Rapture/discussions

Version History

Current Version

Comprehensive spawn system modification
Weapon and enemy balance editing
Loot table rebuilding
Plasmid cost adjustment
Vending price modification
Preset system
Educational documentation

Future Plans

Happy modding, and enjoy your return to Rapture! 🌊

Name		Name	Last commit message	Last commit date
core		core
images		images
presets		presets
tools		tools
README.md		README.md
README.txt		README.txt
_dump_tonics.py		_dump_tonics.py
_parse_shockgame_u.py		_parse_shockgame_u.py
_scan_all_cut.py		_scan_all_cut.py
_scan_cut_content.py		_scan_cut_content.py
_test_teleport_fix.py		_test_teleport_fix.py
war_in_rapture.py		war_in_rapture.py

Latest commit

History

Folders and files

Repository files navigation