Bloodborne Standalone Randomizer
================================

This package independently randomizes item locations, ordinary enemies and
bosses, for an existing Bloodborne installation (CUSA03173, version 1.09,
played on shadPS4).
It does not need Python or .NET. It does not install or replace BBLauncher,
activate BBLauncher mods or connect to a server. Supported release use is shadPS4 through BBLauncher. Existing game files and
saves stay untouched. bbhost integration remains experimental and unverified.

You need:
- Bloodborne CUSA03173 updated to 1.09, installed for shadPS4.
- BBLauncher, started at least once so it has a Mods folder.

Extract this whole folder somewhere of its own (not inside the game or
BBLauncher folders) and keep all of its files together.


Quick start (desktop app)
-------------------------

1. Double-click BloodborneRandomizer.exe. A window opens.
   Windows may show a warning for a new program. Check the release checksum
   and consult the final release notes for signing status before running it.
   (BloodborneRandomizerGUI.exe is the same window without the brief
   console flash; either works.)

2. Game folder: choose your Bloodborne folder, usually named CUSA03173 (the
   one containing dvdroot_ps4 and sce_sys). Choosing dvdroot_ps4 itself also
   works. If shadPS4 keeps the 1.09 update in a separate folder next to the
   game (CUSA03173-UPDATE or CUSA03173-patch), the app finds and uses it
   automatically; update files take priority over the base game, as in
   shadPS4. The app checks the game version and the files it needs before it
   starts.

3. BBLauncher Mods folder: choose the folder named Mods inside your BBLauncher
   folder (choosing the BBLauncher folder itself also works). Never choose
   "Mods-Active (DO NOT DELETE)".

4. Seed: keep the rolled seed, press Roll for another, or type your own. The
   same seed and options always produce the same randomization.

5. Options:
   - Goal: which ending completes the run (default: Childhood's Beginning,
     the Moon Presence ending).
   - Include DLC (The Old Hunters) item locations (default: off).
     Every seed uses the full item pool.
   - Items, ordinary enemies and bosses are independent choices. Items are
     on by default; ordinary enemies and bosses are off for new settings.
     The Bosses only preset leaves items and ordinary enemies to the game
     or an external randomizer. See the release exclusions below.
   - Advanced boss options (used with bosses on):
       Boss pool: Reviewed (default) or Only the good bosses (experimental),
       No Winter Lanterns (default: off).
   Randomizing enemies reads more of your game files (maps, AI scripts,
   events, effects and animations) and needs a few GB of free space while it
   works. Boss shuffle is EXPERIMENTAL: some shuffled fights may still be
   broken. See "Boss shuffle" below.

6. Press Randomize. The log shows progress; enemy randomization can take
   several minutes. When it finishes, the app tells you the name of the new
   package, for example Bloodborne-Standalone-K7QF2-M9XRA-1a2b3c4d5e6f.

7. Close Bloodborne if it is running. Open BBLauncher, go to its Mod Manager,
   deactivate any other randomizer package, and activate the new package.
   Start the game from BBLauncher.

The app writes only to BBLauncher's Mods folder (one new, inactive package)
and to its own data folder:

  %LOCALAPPDATA%\BloodborneRandomizer
    builds\     verified builds, used to re-check exported packages. After
                a successful run the app removes a build older than a day
                when a newer identical build replaces it, or when its
                package is gone from BBLauncher and the app has set that
                package's receipt aside. Other builds are kept.
    receipts\   export receipts (kept outside BBLauncher on purpose)
    logs\       one log file per Randomize click
    settings.json  last-used folders and options

If something goes wrong, use "Copy log" or "Open log folder" and include the
log when asking for help. The exporter refuses to overwrite an existing
package, to write into Mods-Active (DO NOT DELETE), or to export anything that
differs from its verified build; the app shows those refusals as messages and
never activates the package. Running the same seed and options again reuses
the existing package if it is still byte-for-byte identical.


Advanced: command line
----------------------

BloodborneRandomizer.exe is also a console program for scripted use. The
examples below use PowerShell. Replace paths with your own paths. --game-root
accepts the same folders as the desktop app (CUSA03173, its dvdroot_ps4, or
a folder containing CUSA03173) and, like the app, reads a separate
CUSA03173-UPDATE or CUSA03173-patch folder over the base game. It copies the
original files it needs into a temporary folder next to --output while it
works, so the same seed and options give the same package as the app.

1. Build a verified local overlay

Item randomization:

  .\BloodborneRandomizer.exe build `
    --game-root "D:\Games\CUSA03173\dvdroot_ps4" `
    --seed "my-seed" `
    --output "D:\BBRandomizer\my-seed-overlay"

Items plus ordinary enemies (scaled for where they now stand):

  .\BloodborneRandomizer.exe build `
    --game-root "D:\Games\CUSA03173\dvdroot_ps4" `
    --seed "my-seed" `
    --output "D:\BBRandomizer\my-seed-overlay" `
    --randomize-enemies

--randomize-enemies changes ordinary enemies only. Add --randomize-bosses
to shuffle bosses independently. Add --no-randomize-items for a boss-only
or enemy-only build. Add --boss-pool good for "only the good bosses" (experimental) and
--no-winter-lanterns to replace Winter Lanterns' normal spawns. It reads the
map, script, event, effect and animation files it needs, as the app does, and
needs a few GB of free space next to --output while it works.

The output path must not already exist and must stay outside the game folder
(and outside its update folder).
The builder reads the original game files and writes a new overlay directory.
It verifies its native writer receipts and records exact file hashes.

Run this for every available build option:

  .\BloodborneRandomizer.exe build --help

2. Export for the existing BBLauncher

To create a ZIP that can be extracted into BBLauncher's Mods directory:

  New-Item -ItemType Directory "D:\BBRandomizer\exports"
  .\BloodborneRandomizer.exe export `
    --overlay "D:\BBRandomizer\my-seed-overlay" `
    --zip-root "D:\BBRandomizer\exports" `
    --receipt-root "D:\BBRandomizer\exports"

Extract the ZIP directly into BBLauncher\Mods. The archive contains one
top-level mod folder. Open your existing BBLauncher and activate that folder
with its Mod Manager.

To write the package directly into an existing inactive Mods library, keep the
receipt somewhere outside the BBLauncher directory:

  New-Item -ItemType Directory "D:\BBRandomizer\receipts"
  .\BloodborneRandomizer.exe export `
    --overlay "D:\BBRandomizer\my-seed-overlay" `
    --mods-root "D:\BBLauncher\Mods" `
    --receipt-root "D:\BBRandomizer\receipts"

The exporter refuses Mods-Active (DO NOT DELETE), existing package names,
unexpected game-data paths, missing files, extra files, and hash drift. It
never activates the package.

3. Verify an export

  .\BloodborneRandomizer.exe verify `
    --package "D:\BBRandomizer\exports\Bloodborne-Standalone-my-seed-ABC.zip" `
    --receipt "D:\BBRandomizer\exports\Bloodborne-Standalone-my-seed-ABC.export-receipt.json" `
    --overlay "D:\BBRandomizer\my-seed-overlay"

Use the exact generated names printed by the export command. Supplying the
overlay checks the exported files and their original build provenance.

Running BloodborneRandomizer.exe with no command, or with "gui", opens the
desktop app.


Boss shuffle
------------

Boss shuffle swaps which boss fights in which boss arena, using the same
reviewed encounter builder as the Archipelago launcher. It has its own
"Randomize bosses" control. The "Reviewed" pool is the default. "Only the
good bosses" is experimental and also uses Chalice Dungeon bosses.

Gehrman stays unchanged and is excluded as a donor. The One Reborn is
excluded as a donor everywhere. Reviewed mode leaves his native encounter
unchanged and randomizes 20 arenas; Only the good bosses still replaces his
arena and randomizes 21 families and arenas. Oversized bosses cannot replace
Micolash; Blood-starved Beast remains eligible.

Status: experimental. Every build passes the builder's file and receipt checks,
and boss shuffle is still being play-tested, so a shuffled fight may be broken
or unwinnable. If one is, include the log when reporting it, then build again
with a different seed, or with enemies and bosses off.


Safety and compatibility
------------------------

- Keep original game files, generated overlays, exports, and receipts in
  separate directories.
- Deactivate conflicting mods in BBLauncher before activating a generated
  randomizer package.
- The package contains generators, native writers, and derived data tables.
  For boss shuffle it also contains the decompiled text of the game's event
  scripts that the boss builder needs (in one data file). It contains no game
  archives, game binaries, player game files, or save data. Every build reads
  your own installed game files.
- A valid build or export receipt proves byte integrity. It does not claim that
  a seed has completed live gameplay testing.


Hunter's Dream / bbhost companion (experimental, offline only)
-------------------------------------------------------------

This is future integration work, not a supported runtime for this release.
No companion binary is included; full-host compilation and in-game
composition remain unverified. Use shadPS4 through BBLauncher for release play.

Hunter's Dream here means the bbhost project, not a restriction to the Dream
arena. The experimental bbhost runtime and Bosses only preset are intended to let bbhost
shuffle ordinary enemies within their own map while this tool manages bosses.
Items remain vanilla when our item randomization is off. The companion keeps
bbhost shop/chalice randomization and roaming bosses off.

Stock bbhost cannot compose these maps correctly: its mod files take priority
over its enemy randomizer's generated maps. This package includes the source
patch and instructions in BBHOST-COMPOSITION.md. A companion binary must pass
the capability check before the app allows an offline launch. No companion
binary is included, and runtime gameplay acceptance remains outstanding.

Do not manually install this combination in stock bbhost or use it online.
A successful build receipt proves the generated files, not multiplayer
compatibility. Use the app's guarded companion path and read its limitations.
