# Running bbhost ## What you need bbhost contains no game data. You bring: 1. **The game files**: a dump of Bloodborne with the 1.09 update's files copied over it - the folder that contains `dvdroot_ps4`. Its `sce_sys/param.sfo` says `APP_VER 01.09`. The update can also stay in a folder of its own beside the game's, named after it with `-UPDATE` (or `-patch`) appended - `CUSA00900` and `CUSA00900-UPDATE`, the way shadPS4 keeps a game library. bbhost then reads every file the update has from there and the rest from the game folder, as the console applies an update; the log names the folder (`FS update=`). 2. **The 1.09 eboot**, decrypted to an ELF. Its SHA-256 must be `941f887a562aae054fac35af8cc8f27cf075f3d4cc2e029fb5ae2a663aaa5ae7`. Every patch, hook and engine layout in bbhost is an address in that build, so any other eboot stops at start with its hash and the version its dump reports. A dump without the update carries the 1.00 eboot, which will not do. When `paths.eboot` is not set, the game's own `eboot.bin` is used if it is decrypted already (a dump made for shadPS4), the update folder's first. Both must come from a copy of the game you own. And a PC with: - x86-64 Windows 10/11 or Linux - a processor with AVX, SSE4.2 and POPCNT: an Intel Core of the 2nd generation (Sandy Bridge) or newer, or an AMD FX or newer. The game's code also uses BMI1, LZCNT and MOVBE, which Intel's 2nd and 3rd generation Core and AMD FX before Excavator lack; there bbhost rewrites each of those instructions at load into code of its own that gives the same result (the log's `cpu:` and `legacy cpu:` lines say so; `BBHOST_LEGACY_CPU=1` forces that on a newer processor, `=0` off). Without AVX bbhost says what is missing and stops. - a GPU with a Vulkan 1.3 driver (recent NVIDIA, AMD or Intel; the Steam Deck works) - 16 GB of RAM and 8 GB of video memory are recommended. Less can do: 6 GB NVIDIA cards play at 1080p, an RTX 4070 held to a 4 GB card's video memory kept 60 fps at 1080p even in the Nightmare of Mensis, and an integrated Radeon 680M runs about 60 fps at 960x540 and 27 at 1080p (at a Central Yharnam lamp) ## First run Started without a configuration, bbhost opens its setup window: pick the game folder and the eboot (both are checked as you go), choose the online server and account if you want to play online, and press Play. The window writes the per-user `bbhost.toml` and starts the game. `bbhost --setup` opens it again. Over Play, on every page, **Discord** opens the community's Discord invite and **Website** opens thehuntersdream.com, each in your browser. The game turns its shaders into HLSL and compiles them on your PC in the background, so you can play straight away; the first session uses the translator's own shaders while that runs, and may stutter a little more than later ones the first time it meets each place. To compile before playing - after installing or updating bbhost or your graphics driver - open the setup window's Shaders tab and press **Compile shaders now**: every shader of the game's, the pipelines your earlier sessions drew and those on the list a release ships (`pipeline-list.bin`, below), then the first session needs no compiling in the background. (The few pipelines a place needs the first time you ever visit it are still built then.) The tab shows whether the shader caches are up to date for this bbhost and this driver, and the compile's progress, time left and any failures; it can be cancelled, and what was compiled is kept. When the caches are missing or out of date - a new install, a bbhost update that changed the shader translator, a new graphics driver - the tab, and a line on the main tab, recommend it with the time it is likely to take; it is never forced. The same tab has the Shaders setting (HLSL, or Lifted for the translator's own shaders only; also F10 under Graphics, and HLSL Shaders in the game's System > PC Graphics). `bbhost --compile-shaders` does the same from a terminal. Without a display (a headless run) bbhost writes a template config instead and tells you which paths to fill in. ## Configuration `bbhost.example.toml` lists every setting with its default. The configuration is read in layers, each overriding only the keys it sets: 1. the per-user `bbhost.toml`: `%APPDATA%\bbhost` on Windows, `$XDG_DATA_HOME/bbhost` or `~/.local/share/bbhost` on Linux, beside the data folder (`BBHOST_CONFIG_DIR` replaces the folder); 2. `bbhost.toml` next to the executable, or in the working directory; 3. `--config `; 4. the command line: `--app0 `, `--data `, `--eboot `, or the eboot as the last argument. A `bbhost.toml` next to the executable (or in the working directory) wins: it is read after the per-user one, and the setup window, the patch menu and the plugins save to it instead - a copy of bbhost kept with settings of its own. Without one, they save to the per-user file. (`--config` and `BBHOST_CONFIG_DIR` keep saving to the per-user one.) The first log line names every file it read. Paths may use either slash; a relative path is taken from the folder of the file it is in. The in-game settings (F10, or the PC Settings, PC Graphics and Key Bindings entries the game's own System menu gains) are saved beside the per-user config in `bbhost-options.toml` - or in one next to the executable, when there is one there. Older versions kept the Linux settings in `$XDG_CONFIG_HOME/bbhost` or `~/.config/bbhost`. At each start bbhost moves what it keeps there - `bbhost.toml`, the `bbhost-options*.toml` files, `plugins` and `patches` - to the new folder, and the setup window says what moved until you dismiss it. Nothing is overwritten: a file the new folder already has stays in use, and the old one goes beside it as `.from-config-`. Anything else in the old folder is yours and stays there, so a path in `bbhost.toml` that points into it keeps working (a relative one is written out in full). A linked or read-only old folder is copied rather than emptied, and a start that cannot move it uses the old folder as it is. ## Saves Saves are in `/saves/SPRJ0005`, where `` defaults to `%LOCALAPPDATA%\bbhost\data` or `~/.local/share/bbhost/data`. The game writes a save into a copy beside it, `.SPRJ0005.stage`, and bbhost then moves the copy's files into `SPRJ0005` one by one, under a list in `.SPRJ0005.commit` (on Linux, where the file system can swap two folders in one step, it swaps them instead). If bbhost ends in the middle, its next start finishes the save or drops it, so `SPRJ0005` always holds a whole save, the new one or the one before; leave the copy and the list alone. On Windows the `SPRJ0005` folder itself never moves, so a File Explorer window open in it stays open. Each time the game writes a save (at most every five minutes) a copy goes to `/save-backups/`, and the newest eight are kept. To restore one, quit and copy its files over `/saves/SPRJ0005`. The shader caches in `/bbhost` (`translation-cache.bin`, `vulkan-pipeline-cache.bin`) belong to the shader translator that made them, which `shader-cache-build.txt` names. An update that leaves the translator alone keeps them, so it starts as fast as the build before it; one that changed the translator throws both away (`gpu: shader caches made by translator ..., this is translator ...: cleared`) and builds them again while the title and the loading screens are up, from the two lists beside them, which are kept: `stage-manifest.bin`, the shaders the game's draws needed that it never creates itself, and `pipeline-manifest.bin`, every graphics pipeline a draw created. At each start bbhost builds every pipeline on that list again in the background, its shaders, its pipeline libraries and its optimized link, so what an earlier run has drawn is not compiled again when it comes into view. The lists hold what the game drew, not what bbhost made of it, so they outlast translator updates and driver changes: what they build is made again from them. A list `pipeline-list.bin` beside `bbhost` (or the one `BBHOST_PIPELINE_LIST` names) adds its pipelines to a player's own, so a first start has them too; such a list names the game's shaders, the player's own bundles supply them. `BBHOST_KEEP_SHADER_CACHE=1` keeps the caches anyway, `BBHOST_PIPELINE_MANIFEST=0` leaves the pipeline list out. The files are safe to delete: the next start builds them again. ## Controls A controller works as on the console. Without one, the keyboard and mouse take over and the button prompts follow: the mouse turns the camera and works in the menus, and every action can be rebound (F10 or the game's Key Bindings menu) - to a key, any of five mouse buttons, or the wheel turned up or down (each notch a press). In the world the wheel zooms the camera, each notch a step of Camera distance (up closer, down further out), and the middle button puts it back at the game's own distance: Camera Zoom In, Out and Reset on the Key Bindings menu's Other page, which a player can rebind (Transform, on the middle button too until then, keeps C). Hold Left Alt with the movement keys to walk, and two opposite keys held together cancel, both as in Dark Souls III. The game's menus take keys of their own, as Dark Souls III keeps a menu's apart from play's: the arrows or the movement keys move, Return or Interact confirms, Backspace or Dodge goes back, Page Up and Page Down turn the page or the tab (L1 and R1), Home and End are a menu's two shortcuts (L2 and R2: the storage box's Show Storage and Show Inventory) and F and R its display and status switches (Square and Triangle) - the Key Bindings menu's Menu Pages and Options page. The attacks, the firearm, Transform, the Blood Vial and the quick item work in play only, so their keys do nothing in a menu, and a menu's key may also be one of theirs. F9 opens the patch and plugin menu and F10 bbhost's own settings: menus over the game in the setup window's look, moved through with the mouse, the arrow keys or a controller (the d-pad and A, L1 and R1 for the pages, B or Escape to close). In F9's Patches page most patches turn on or off at once; the rest (render targets sized as the game starts, code bbhost itself rewrites) at the next start, and the page says which. The menus answer at once. In the game a menu that closes on a choice - backing out of the inventory or the pause menu, an item's command menu, Continue on the title - holds the choice back until its fade-out has played (a tenth of a second, a fifth in some) and drops any press made meanwhile; bbhost passes the choice on as the press lands, and the menu behind takes input while it fades back in. The message, Yes/No and quantity boxes take OK as soon as they are up (the game ignores it for their first half second). The loading screen keeps its fade-out. `BBHOST_MENU_FADE_WAIT=1` keeps the game's waits. The mouse turns the camera the way Dark Souls III's PC version does: by an angle for each count the mouse reports, with no acceleration, no dead zone and no top speed, at any frame rate. Mouse sensitivity sets the angle, from 0.005 degrees a count at 0 to 0.4 at 100, each step about 4.5% further than the one below; the default, 50, is 0.045, which suits most mice at 800 to 1600 DPI. (Dark Souls III's own scale ran from 0.1 to 0.4, too fast for most mice at its slowest; a setting saved before v0.2.28 keeps the angle it had, unless it was the old default.) The right stick turns it as on the console, and while the stick is moving the mouse waits. With a target locked on, a quick flick of the mouse switches targets. Mouse Sensitivity and inverting either axis are on the game's System > PC Controls page, and with the other input settings in F10 and the setup window; the game's own Camera Sensitivity, under Controls, is the stick's. With the mouse, the camera also stays where you put it: it does not turn by itself as the character moves - following the character round, or turning away from walls. Lock On with no target (Q) still swings it round behind the character. That follows the device you used last: pick up a controller and the game's own camera is back; touch the keyboard or mouse and it holds again. Mouse Auto-Rotation on the PC Camera page (F10: Mouse auto-rotation) turns it back on for the mouse too. It is the community's "Disable Camera Auto Rotation via Movement" patch made part of the camera - less its hold on the lock-on button's recentre; that patch, applied as before, still works as it always did, with any device. The character's name, a chalice glyph and the network password are typed in a box over the game, which stands in for the console's on-screen keyboard: Enter accepts, Escape cancels, Backspace deletes and Ctrl+V pastes. A controller's Cross (A) accepts and Circle (B) cancels. The boxes take what the console's keyboard offers - letters, digits and punctuation from plain ASCII - and a glyph takes its own 32 characters, lowercased as they are typed. The name box starts from `[player] name`, which the first key typed replaces; `[player] ime = "auto"` answers it with that name instead. ## Logs bbhost logs to standard error. The packages' `run-bbhost.bat` (Windows) and `run-bbhost.sh` (Linux) write each session's log to `logs/`. A bug report is most useful with that log attached. The game's own prints go to the console too. A line it prints over and over (YEBIS's depth-of-field error in parts of Cainhurst comes every frame) is written once, then as a count every ten seconds while it keeps coming and at exit: "the game printed this N more times". `BBHOST_GUEST_PRINTS=all` writes every line as it comes. The setup window's Settings page has **Tooling and logging** (`[debug] tooling`; `BBHOST_TOOLING=0` or `1` for one run), on by default: the log itself, the periodic reports in it, the stall detector, the GPU busy meter beside the FPS counter, the bottleneck meter's `perf summary:` lines, which say what limits the frame rate ([docs/performance.md](performance.md)), and the history of recent draws. Off gives the game the time they take, and nothing is logged - not bbhost's lines, not the game's own prints - and on Windows no log window opens: bbhost.exe is a GUI program, whose log takes the file or pipe it was started with (`run-bbhost.bat`'s), the terminal it was started from, or else a console window of its own, all only while the log is on. A crash's report is still written to wherever the log would go. `BBHOST_LOG=1` keeps the log with tooling off (a test measuring with tooling off that still reads the log). Leave it on when reporting a problem. ## Troubleshooting **The eboot is refused.** It is not the 1.09 build. Use the update's `eboot.bin`, decrypted; the message says what the dump's `param.sfo` reports. **The game stops at start in `FileTransferTask.cpp(865)`, or the log says `patch: old-hunters skipped`.** The game folder holds files older than the 1.09 update's: the update was never copied over it, or only its new files were (Windows' "Skip these files" when it asks about the ones already there). The log's `change appearance: off - not the 1.09 m21_00_00_00 layout` says the same. Copy the update's files over the game folder again, replacing the ones there, or keep the update in a `-UPDATE` folder beside it (above). Until The Old Hunters' own files are there, bbhost leaves the game as the edition without it: its title screen would otherwise be a flat green picture. **The graphics card stops responding.** When the GPU hangs and the system resets it, nothing can be drawn again in that session; bbhost stops the sound, says so in a box and exits. Loading screens run with the GPU's progress markers, so the log of a hang in one names the draw that hung and how far past it the GPU had got - send that log. `set BBHOST_GPU_CHECKPOINTS=amd` in run-bbhost.bat (`BBHOST_GPU_CHECKPOINTS=amd` before the command on Linux) marks the whole game, at some cost to the frame rate. Overlays that hook Vulkan are a common cause: OBS's game capture is kept out automatically on AMD cards (`[video] obs_capture` changes that), and OBS's Window Capture records bbhost without any hook. **A crash just after arriving somewhere, with `fmod ring:` in the log.** FMOD, the game's sound library, lists every sound it has loaded, and it frees the one subsound object a stream of many sounds (a voice bank) shares even when that object refused to be released because an event still plays it - leaving it in the list. The next sound loaded beside it then writes into memory the game has used again since. bbhost takes such a sound out of the list first and keeps it, marked so that nothing plays it again; the log's `fmod ring:` lines say when it did, and the one at exit how many it kept (a few hundred bytes each that are never freed). `BBHOST_FMOD_GUARD=0` is the game's own behaviour; `BBHOST_FMOD_CHECK=1` also logs FMOD's sounds as they come and go and checks the list as sounds are loaded. **A crash on a loading screen, or `sf lock:` / `sf text:` in the log.** Scaleform, the game's menu library, expects one thread at a time in a menu. The game updates its in-game HUD - the bars, the boss list, the map name - on a worker thread that does not take the HUD's lock, while another worker runs the HUD's own animation and hands its changes to the renderer. A text changed during that hand-over reaches the renderer without its layout, and the renderer's first use of it crashes the game; two threads in one menu at once can also break its lists. bbhost has the HUD's update take the HUD's lock, as the game's own menu jobs do; the `sf lock:` line at exit says how often it waited and for how long, and `BBHOST_SF_MOVIE_LOCK=0` is the game's own behaviour. Behind it, a text that still arrives without a layout skips the part of its update that needs one until the layout arrives (`sf text:`; `BBHOST_SF_TEXT_GUARD=0` turns that off). `BBHOST_SF_TEXT_CHECK=1` also counts the menus' changes by whether the thread making them held the menu's lock, and names the game code behind the others. **Wrong picture.** Wrong colours, a green or black screen, missing parts: press F12 in the game while it shows. bbhost writes that frame, every render target the last draws wrote and the draw list into a folder of its own beside the logs, `logs/f12--