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

This package independently randomizes item locations, ordinary enemies and
bosses, for an existing Bloodborne installation (CUSA03173 or CUSA00900, version 1.09,
played on shadPS4 or BBPort).
It does not need Python or .NET. It does not install or replace BBLauncher,
activate BBLauncher mods or connect to a server. BBPort exports are experimental;
upstream Linux gameplay validation is pending. Existing game files and
saves stay untouched. bbhost integration remains experimental and unverified.

You need:
- Bloodborne CUSA03173 or CUSA00900 updated to 1.09, installed for your runtime.
  CUSA00900 supports Chalice Dungeon bosses too, and has not yet
  been gameplay tested; see "Other regions" below.
- BBLauncher, started at least once so it has a Mods folder, or BBPort with
  a merged 1.09 game folder and its mods folder already created.

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


BBPort
------

Close BBPort and Bloodborne before generating or exporting a seed. Choose
BBPort in Runtime and the same merged 1.09 game folder used by BBPort. A
separate shadPS4 -UPDATE/-patch folder is refused: apply the update to your
BBPort installation first. CUSA03173 and CUSA00900 keep their existing region
restrictions; this target does not add support for other game serials.

Choose the exact mods folder configured on BBPort's Mods & patches page
(normally <BBPort folder>\mods; custom names are supported). This is remembered
separately from BBLauncher's Mods folder. The export contains only native
dvdroot_ps4 paths, while verification receipts stay in the randomizer's data
folder. BBPort's settings, mod order, game files and saves are not changed.

IMPORTANT: BBPort enables new mod folders automatically. Before playing, open
Mods & patches, enable Load mods and disable older randomizer seeds and any
conflicting mods. Keep only the intended seed enabled. Lower entries in the
list load later and win conflicts.

CLI: add --runtime bbport to the build command, then export that overlay with
--mods-root "D:\BBPort\mods" (or create an extraction-ready ZIP with --zip-root).
The export receipt records BBPort as the target and verifies the same bytes.
Items, ordinary enemies and bosses are available. The exported files are
verified. A limited Windows playtest used Awakenchan/BloodBorneButPc v0.9.23:
vanilla Cleric Beast combat worked, and the player confirmed the randomized
Living Failures encounter loaded. That encounter ended before its shared
health bar emptied; the completion bug is under investigation. This is not a
full playthrough or validation of canonical Linux BBPort.


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 or CUSA00900 (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 (for example CUSA03173-UPDATE or CUSA00900-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. Runtime: choose shadPS4 or BBPort. For shadPS4, choose the folder named Mods inside your BBLauncher
   folder (choosing the BBLauncher folder itself also works). Never choose
   "Mods-Active (DO NOT DELETE)".
   For BBPort, see "BBPort" above and choose its configured mods folder.

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: Vanilla bosses (default) or Choose bosses (experimental),
       No Winter Lanterns (default: off). See "Boss shuffle" below.
   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. For shadPS4: 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 the selected mods folder (one new 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 (the game folder, its dvdroot_ps4,
or a folder containing one game) and, like the app, reads a separate
<game>-UPDATE or <game>-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.


Tracker
-------

  .\BloodborneRandomizer.exe track
  .\BloodborneRandomizer.exe track --dock
  .\BloodborneRandomizer.exe track --plan "D:\Path\To\Mods\Bloodborne-Standalone-..."

The tracker shows which areas you can reach and which checks are in logic,
area by area, for the seed you randomized most recently (or the package or
build folder you name). It only reads the running game; it never changes it,
and it shows where checks are, never what they hold.

It follows the first character the game saves after it starts. Start it
before or after the game; start it again to follow a different character.
--dock lays it over the right edge of the game window: F6 hides it, then
shows areas, then the checks in logic; F7 and F8 page that list;
Ctrl+Shift+F10 undocks it. Docking needs windowed or borderless mode.

If nothing but questline checks is left in logic, the tracker offers a Hint
button. Each press names one check that would open the way, and the count of
hints used is shown. Hints are saved under %LOCALAPPDATA%\BloodborneRandomizer
\tracker, never in the package. Turn the button off in the tracker's settings
if you want no help at all.

Seeds randomized before this release cannot be tracked; randomize again.


Other regions and compatibility inspection
------------------------------------------

CUSA03173 1.09 is the tested release. CUSA00900 1.09 is supported because
every game file the item, DLC, enemy and reviewed boss options read is
byte-identical to CUSA03173: the same seed gives the same package. Its
Chalice Dungeon bosses use available donor maps from the installed region.
CUSA00900 has not been gameplay tested.

"inspect" reads an installation and writes a JSON compatibility report:

  .\BloodborneRandomizer.exe inspect `
    --game-root "D:\Games\CUSA00900\dvdroot_ps4" > compatibility-report.json

--game-root accepts the same folders as build (the game folder, its
dvdroot_ps4, or a folder containing one game); a separate update folder is
read over the base game. Inspection only reads files. The report lists the
title ID and version, SHA-256 hashes of the parameter, map and event files,
and a comparison of every catalogued item award with the bundled item writer.
It contains no game file contents and no absolute paths. Review it before
sharing. Matching item fields alone do not prove that events, enemies, DLC
or gameplay work.

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 and two pools:

- Vanilla bosses (default): the main game's own bosses trade arenas, each
  boss once. The One Reborn's encounter stays unchanged, so 20 arenas change.
- Choose bosses (experimental): tick the bosses you want, from the main game
  and the Chalice Dungeons, or use a preset (Main game, Good bosses, Chalice
  Dungeon, All). All 21 arenas, including The One Reborn's, are filled from
  your choice. With fewer than 21 bosses they repeat, as evenly as possible;
  with more, 21 of them are picked by the seed. "Good bosses" is the former
  "Only the good bosses" pool.

Any boss can fill every arena, so a single boss is a valid choice (for
example, Orphan of Kos everywhere). A chosen boss's own arena keeps its
vanilla fight when the seed puts it there, which happens only when there is
no other way to fill every arena. Gehrman stays unchanged and is not offered;
neither is The One Reborn. Oversized bosses cannot replace Micolash
(Blood-starved Beast still can); when no chosen boss fits there, Micolash
keeps his vanilla fight. Chalice Dungeon bosses support both CUSA03173 and
CUSA00900 1.09.

From the command line, use --boss-pool vanilla (the default) or
--boss-pool custom --bosses with comma-separated names and presets, for
example:

  --boss-pool custom --bosses father-gascoigne,lady-maria,preset:chalice

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.
