[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-105344":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":17,"stars30d":17,"stars90d":16,"forks30d":16,"starsTrendScore":18,"compositeScore":19,"rankGlobal":10,"rankLanguage":10,"license":20,"archived":21,"fork":21,"defaultBranch":22,"hasWiki":23,"hasPages":21,"topics":24,"createdAt":10,"pushedAt":10,"updatedAt":30,"readmeContent":31,"aiSummary":10,"trendingCount":16,"starSnapshotCount":16,"syncStatus":32,"lastSyncTime":33,"discoverSource":34},105344,"bloodborne_mac_port","Wooloomooloo2\u002Fbloodborne_mac_port","Wooloomooloo2","Bloodborne on Apple Silicon Macs: the PS4 game's own code under Rosetta 2, rendered natively with Metal (MetalFX, FSR 3.1). Work in progress.","https:\u002F\u002Fdiscord.gg\u002FNuqDHMyNk",null,"C++",247,13,3,24,0,14,42,67.84,"GNU General Public License v2.0",false,"master",true,[25,26,27,28,29],"apple-silicon","bloodborne","macos","metal","ps4","2026-11-01 00:14:43","# bloodborne_mac_port: Bloodborne on macOS (Apple Silicon)\n\nA **work-in-progress macOS port** of the native Bloodborne PC port. It runs the original PS4\nexecutable of *Bloodborne* (CUSA03173, version 1.09) on Apple Silicon Macs: the game's own\nx86-64 code executes directly under **Rosetta 2**, PS4 system libraries are replaced by a\nlightweight HLE runtime written in C, and GPU command buffers are translated by a\n**shadPS4-derived video core** into **native Metal** (since 0.5.0; MoltenVK before).\n\nThis is not an emulator and contains no game code: the loader and runtime run your own copy of\nthe game as an x86-64 process under Rosetta 2, and rendering happens in a separate native arm64\nprocess.\n\n> **No game files or copyrighted assets are included, and none will ever be distributed.**\n> You must provide your own legally dumped and decrypted copy of Bloodborne (CUSA03173 v1.09).\n> This project is not affiliated with or endorsed by Sony Interactive Entertainment,\n> FromSoftware, or AMD.\n\n**Video guide:** Andrew Tsai has made a video guide to this port:\n[watch it on YouTube](https:\u002F\u002Fwww.youtube.com\u002Fwatch?v=_QgmfFyZbYo). Thank you, Andrew, for\ntaking the time to make it!\n\n## Status (2026-10-31)\n\n**Current version: [mac-v0.5.12](https:\u002F\u002Fgithub.com\u002FWooloomooloo2\u002Fbloodborne_mac_port\u002Freleases\u002Ftag\u002Fmac-v0.5.12)** (download the app, or build it as below).\n\n**Work in progress, playable.** On an Apple M4 Max the game boots, character creation works,\nsaves load, and the game runs at a **locked 60 FPS** at 1080p and 1440p native, and now at\n**4K native too** (70 FPS uncapped in Hemwick), or upscaled with MetalFX, FSR 3.1 or TAA,\nthrough its own **native Metal renderer**. Expect occasional rendering glitches (see\n[Known issues](#known-issues)).\n\nThe target is a locked 60 FPS (the game's physics run at 30 Hz), with even frame pacing, at the\nhighest resolution each Mac allows; 90 and 120 FPS caps are there for ProMotion displays.\n\n**Releases:** 0.5.12 is the last 0.5.x release. **0.6** will be **MetalFX frame generation** (#64,\nfrom @evill33t): it comes out as pre-releases first and only becomes the default once it's well\ntested.\nThe opening-movie freeze and crash are fixed in 0.5.8, the slowdowns on 16-18 GB Macs (#69)\nin 0.5.9, 0.5.10 adds rebindable controls, 0.5.11 fixes 5120×2160 and a crash after long\nsessions, and 0.5.12 fixes that crash's follow-up. Online play (#9) is still in progress.\n\n### New in 0.5.12: the last 0.5.x release\n\n- **Fixed: the crash after long sessions, again** (#113; \"signal 11 at guest offset 0x216a08c\",\n  after about 90 minutes). 0.5.11 skipped the game's render bind for a resource that was gone,\n  but the game then also released it and asked for its value. Both are now skipped as well\n  (#114, from [@evill33t](https:\u002F\u002Fgithub.com\u002Fevill33t)).\n- **Fewer false \"the GPU stopped making progress\" exits** (#106): the GPU watchdog now also\n  watches the GPU's own completion signal, so CPU-side delays no longer count as a GPU stall. A\n  real GPU stall still ends the game, so it cannot freeze the Mac's display (#107, from\n  @evill33t).\n- **L3 + R3 can be switched off** (#104): the launcher's **Controls** page and the in-game menu\n  (**Controller**) have a switch for it, for players who press both sticks by accident. ⌘, still\n  opens the menu.\n- **Known:** above 1920×1080 with the upscaler off, the game's own anti-aliasing doesn't reach\n  the picture (#115), so edges can look sharper and more jagged than at 1080p. Until that's\n  fixed, try **MetalFX** with the **Native AA** preset at those resolutions.\n\n### New in 0.5.11: 5120×2160 fixed, a long-session crash fixed\n\n- **5120×2160 now draws the level** (#93). In 0.5.10 the game ran out of its own graphics memory\n  at this size: the city had no buildings or ground, or the game crashed while loading. It now\n  gets a bigger graphics heap and about 2 GB more memory, at this resolution only (about 50 FPS\n  uncapped on an M4 Max in Central Yharnam). The launcher warns on Macs with less than 32 GB.\n- **Fixed: the crash in the Hunter's Dream after long sessions** (#99, #101, #102; \"signal 11 at\n  guest offset 0x2169edc\", after about 90 minutes). The game queued a render bind for a resource\n  that was gone; it now skips that one bind instead of crashing (#100, from\n  [@evill33t](https:\u002F\u002Fgithub.com\u002Fevill33t)).\n- **Fewer GPU-process crashes from stale graphics data** (#98, from @evill33t): if a draw reads\n  graphics data the game has already freed, the renderer reads zeros instead of crashing. If\n  0.5.11 runs slower than 0.5.10 on your Mac, please open an issue with your Mac and settings.\n- **Video guide:** Andrew Tsai's [guide to this port](https:\u002F\u002Fwww.youtube.com\u002Fwatch?v=_QgmfFyZbYo).\n\n### New in 0.5.10: rebindable controls, a crash fix, choose the display\n\n- **Rebindable keys and mouse buttons.** The launcher has a new **Controls** page: every action\n  (movement, camera, buttons, d-pad, Options, touch pad) can take keys or mouse buttons, two per\n  action, and the mouse wheel can be bound too. There is a **walk** key (Left Alt by default:\n  movement keys push the stick half way), a vertical mouse speed, and mouse sensitivity now goes\n  up to 10. The defaults are the 0.5.9 layout, so nothing changes until you rebind something.\n- **Fixed: the GPU process crash in fights** (#74; \"signal 11 in StageSpecialization\", seen\n  fighting Ebrietas and in the Forbidden Woods). The game sometimes leaves a resource table\n  empty; the port read through it and crashed. It now reads zeros there, as the PS4's GPU does.\n- **Choose the display the game opens on** (#60): with a second display connected, the launcher\n  shows a **Display** picker. Full screen opens there too. If that display isn't connected, the\n  game opens on the main one.\n- **5120×2160 (21:9)** native resolution (#93), under **Ultrawide or 16:10** in the launcher\n  (it did not draw the level until 0.5.11).\n- **The mouse cursor hides** after 3 seconds without moving over the game window (#93), and\n  comes back as soon as you move or click.\n- **Updates no longer leave the old launcher open** (#96): after **Install Update**, the old\n  copy stayed on \"Installing…\" beside the new one. This is fixed in 0.5.10's updater, so it\n  takes effect from the *next* update: when updating from 0.5.9, the old window can still stay\n  open once. Quit it with ⌥⌘Esc (Force Quit); the update itself is installed.\n\n### New in 0.5.9: 16-18 GB Macs run at full speed\n\n- **16-18 GB Macs no longer slow down to 10-20 FPS** (#69, #83). The cause was memory, not the\n  GPU: the port kept 6.5 GB of GPU memory pinned (it can never be swapped out), and on a 16 or 18\n  GB Mac that left too little for the game and macOS, so the Mac swapped and the frame rate\n  collapsed. On Macs with 24 GB or less, the game's memory is now mapped to the GPU only where the\n  game actually uses it (3.5 GB pinned instead of 6.5 GB). This is\n  [@MojahedAbushawish](https:\u002F\u002Fgithub.com\u002FMojahedAbushawish)'s work in #85 and #86.\n  - On a Mac limited to behave like an 18 GB Mac: 15-17 FPS before, 58-60 after (1080p, 60 cap).\n  - Players: an M4 MacBook Air 16 GB went from 11-16 FPS to 57-60 (#83), and the M3 Pro 18 GB\n    from #69 plays smoothly.\n  - Macs with more memory keep the previous layout, unchanged. `BB_ARENA_LAYOUT=legacy` in\n    `launch.conf` brings it back on a smaller Mac, if ever needed.\n- If you added `BB_ARENA_GIB` or `BB_GC_BUDGET_MB` to `launch.conf` while testing, remove them.\n- Thank you to @lifeos-creator, @danielsirbubusiness and @khhan0703 for testing the test build on\n  their Macs.\n\n### New in 0.5.8: the opening-movie freeze and crash fixed\n\n- **New games no longer freeze or crash in the opening movie** (#46, #50, #51, #24, #84). Both\n  showed up on slower or busier Macs, which is why they were hard to reproduce on a fast one.\n  - **The freeze** (\"no new frame for 30 seconds\"): when a movie ended and the game closed the movie\n    player at the same moment, the stop request could miss a decoder thread that was waiting for a\n    free frame buffer, and the game waited for it forever.\n  - **The crash** (signal 11 at guest offset 0x26c01c3): during the movie, the game's main thread\n    drew into the render thread's GPU context from a path the port didn't lock. It now runs under\n    the same lock as the others.\n  - On a Mac slowed down on purpose, 5 of 5 new games froze or crashed before the fix; 4 of 4\n    reached character creation after it. Normal play and the benchmark are unchanged (60 FPS).\n- **A hang report:** if the game ever stops responding, the log now lists where every game thread\n  is waiting, so freeze reports can be read from `game.log` alone.\n- **Co-op stability** (from [@noelmiller](https:\u002F\u002Fgithub.com\u002Fnoelmiller), #11): two renderer stops\n  seen in co-op (a render-pass submit and a recording-chunk race) are now survivable.\n- **Safety fixes in the PS4 runtime** (from [@evill33t](https:\u002F\u002Fgithub.com\u002Fevill33t), #80, #81,\n  #82): semaphore handles kept at full width, system-module IDs checked in full before lookup, and\n  guest thread-local storage checked before the runtime is entered.\n\n### New in 0.5.7: mouse look, a Stop button, keyboard fixes\n\n- **Mouse look** (from [@MojahedAbushawish](https:\u002F\u002Fgithub.com\u002FMojahedAbushawish), #20). Turn on\n  **Mouse camera** in the launcher (General → **Controls**) or in the in-game menu (⌘,).\n  - Click once in the game window to turn the camera with the mouse; ⌘ gives the cursor back.\n  - Left click R1, right click L2, middle click R3 (lock on), side buttons R2 and L1.\n  - While Mouse camera is on, the **arrow keys are the d-pad**: they scroll menus, and in game they\n    switch weapons, tools and quick items.\n  - The launcher's **Controls** section lists every keyboard and mouse binding.\n- **A Stop button** (from [@DiAvisoo](https:\u002F\u002Fgithub.com\u002FDiAvisoo), #31). While a game started with\n  **Play** runs, the launcher stays behind it with a **Stop** button; quitting the launcher stops\n  the game too. Exit Game in the game's own menu is still the safe way out, because it finishes\n  saving.\n- **The keyboard works with a controller connected.** Before, a connected controller switched the\n  keyboard off, so Enter or Space could not press Play Offline.\n- **⌘ shortcuts no longer reach the game:** ⌘Q drank a Blood Vial. ⌘W no longer quits the game\n  (from #20).\n- **A safety fix in the frame rate patches.** The community 30\u002F60\u002F90\u002FUncap FPS++ patches wrote a\n  return instruction into the middle of the game's condition wait. Any timed wait reaching it\n  would have crashed; it never showed in play, but now the game's own code runs there. Found by an\n  assessment comparing the port with [Paleblood](https:\u002F\u002Fgithub.com\u002FYharnam-Hunters\u002FPaleblood),\n  verified and fixed independently.\n- **Enemy Control** (patch files only) is refused together with a frame rate patch, because the two\n  change the same code.\n\n### New in 0.5.6: mod manager and cheats, benchmark, 16:10, better crash reports\n\n- **Mods & Cheats** (asked for in #16 by @noelmiller): a **Mods & Cheats…** button in the\n  launcher opens its own window. See [Mods and cheats](#mods-and-cheats).\n  - **Mods:** your loose-file mods in load order, with on\u002Foff switches. You can reorder them, add\n    one from a folder or a .zip, or remove one (it goes to the Trash). A mod that can't load says\n    why, and a conflicts list shows which mod wins each file. Game files are never changed.\n  - **Cheats & Tweaks:** 12 switches for patches the game already had: can't die, enemies don't\n    see or hear you, rally, physics, analog sensitivity, camera distance and auto-rotation, text\n    size, all game languages.\n  - **Patch Files:** on\u002Foff switches for your own shadPS4\u002FGoldHEN `.xml` patch files.\n  - Before the first launch with a new set of mods or cheats, the launcher **backs up your save**.\n- **Benchmark** (in the launcher): a recorded walk through Central Yharnam at 60 FPS, then 30\n  seconds uncapped, with a results window. It measures average and best FPS, 1% and 0.1% lows,\n  hitches during traversal and their likely cause (shader compiles, streaming, GPU, game CPU),\n  plus CPU, GPU, memory, swap and thermal state. It's meant for comparing Macs and for reports\n  about slowdowns. See [Benchmark](#benchmark).\n- **Dated session logs and fuller crash reports** (from [@satperm](https:\u002F\u002Fgithub.com\u002Fsatperm), #40):\n  one timestamped log per session, plus a JSON version for log tools. Warnings go to the macOS\n  system log. Crash reports include macOS's own crash files and a diagnostics zip. See [Logs](#logs).\n- **About panel and update check** (from @satperm, #23), and the **game's own icon in the Dock**\n  (from [@soulripper13](https:\u002F\u002Fgithub.com\u002Fsoulripper13), #66; made in memory from your game\n  folder, never saved).\n- **16:10 resolutions** (#75, asked for by @Frosty2804): 1280×800, 1920×1200 and 2560×1600 under\n  **Ultrawide or 16:10** in the launcher, using Kyo's patches (correct HUD and lock-on positions).\n  That is closer to the shape of MacBook displays, so full screen has thinner black bars.\n- **Audio dropout diagnostics** (from [@DiAvisoo](https:\u002F\u002Fgithub.com\u002FDiAvisoo), #32): opt-in\n  logging of the audio signal, queue and decoder, for reports of crackling or gaps.\n- **Fixes:**\n  - The arrow keys no longer also press the d-pad. Turning left swapped the left-hand item and\n    broke a sprint (#61, reported by @IlyaDylko). IJKL are still the d-pad.\n  - A GPU process stuck on hung GPU work no longer leaves the game hanging after it's killed, so\n    the launcher can start the game again (#71, reported by @wgorecodes).\n  - F9 pad recording (`BB_PAD_RECORD`) works again.\n\n### New in 0.5.5: lifts, crash and upscaling fixes, no more red flashes\n\n0.5.5 is a full release of the 0.5.4.3 to 0.5.4.5 pre-releases, plus one new fix. The first launch\nrebuilds the shader cache once (a minute or so of stutter).\n\n- **Red flashes on breath and other effects** (new in 0.5.5). In cold areas such as Cainhurst,\n  the hunter's breath could flash as a bright red ball every few seconds. The PS4's GPU\n  has float instructions that turn infinities and invalid values into 0 or the largest normal\n  number. The shader translator turned several of them into ordinary maths, and Metal's fast maths\n  removed the checks for invalid values, so one bad pixel bloomed into a red ball. Those\n  instructions now follow the PS4's rules: in testing, flashes went from about 1 frame in 60 to\n  fewer than 1 in 500 with the first half of the fix, and the second half targets the rest. If you\n  still see one, please report where.\n- **Fixed game timing by default, so lifts no longer drop you through the floor.** The port always\n  advanced the game by each frame's measured time, so on uneven frames the character could sink\n  through a moving lift and die. At the 60 and 90 FPS caps the game now runs in fixed steps (the\n  60\u002F90 FPS++ patches); 30 runs the game unpatched, and 40 and 120 stay variable. If a scene can't\n  hold the cap, the game slows down a little instead. **Game timing** under the launcher's frame\n  rate cap (`game_timing` in `bbport.ini`) switches back to variable steps.\n- **The rare \"memmove\" crash is fixed** (#34, #37, #38, #54, #57). The game's render thread builds\n  each frame's commands in a fixed 256 KB pool. It normally uses about 3% of it, but on rare frames\n  it needs more, and the game then copied into a null address and crashed. When the pool runs out,\n  the port now hands the game memory from a 16 MB spare pool and logs a \"Frame pool: … full\" line\n  in `game.log`.\n- **MetalFX and FSR 3.1 no longer turn hazy while moving** (#48, found and measured by\n  @MojahedAbushawish). The camera motion vectors pointed the wrong way vertically on the Metal\n  renderer, so the upscalers blended in history from the mirrored position.\n- **Native AA works again with texture compression on**: since 0.5.4 it, and upscaling above\n  1080p, silently ran without the upscaler.\n- **The launcher no longer freezes on macOS 26.0.1** when switching from Advanced back to General\n  (#47): General and Advanced are now a switch at the top instead of tabs, which hit a SwiftUI\n  bug in that macOS version.\n\n### New in 0.5.4.2: GPU stall crashes fixed\n\n- **\"The GPU stopped making progress\" crashes, and the frame rate sinking over a session, are\n  fixed** (#42, #43, #44, #45, #49, #55). The extra Metal views of GPU memory added in 0.5.4 cost\n  no memory, but macOS's GPU driver counted each one as memory it had to keep in place, until it\n  paged on every frame and the GPU stalled. They are gone; meshes high in GPU memory are copied to\n  a small buffer instead (@DiAvisoo's original fix). Found and measured by @noelmiller.\n\n### New in 0.5.4.1: missing trees\n\n- **Trees and other objects that never drew are back** (#35). The Metal renderer skipped every\n  tessellated draw with more than one instance, which some areas use for whole trees: in the\n  Forbidden Woods, about 1,900 draws every 5 seconds were dropped. Each instance is now drawn on\n  its own; 60 FPS holds there on an M4 Max.\n\n### New in 0.5.4: the biggest speed-up since native Metal\n\nThe same spot in Hemwick Charnel Lane, M4 Max, full screen, upscaler off, frame rate uncapped,\nread from Apple's Metal Performance HUD:\n\n| Output | 0.5.3 | 0.5.4 | |\n|---|---|---|---|\n| 4K native (3840×2160) | 51.3 FPS, GPU 20.1 ms | **70.1 FPS, GPU 14.9 ms** | **+37%** |\n| 4K native, another view | 80.7 FPS, GPU 12.6 ms | **109.1 FPS, GPU 9.3 ms** | **+35%** |\n\nAnd in alternating test runs (M4 Max, uncapped; the presenter stops at 120 FPS):\n\n| Scene | Before | After |\n|---|---|---|\n| Hunter's Dream, 1440p native, texture compression off → on | 101.7–102.1 | **119.6–119.8** (at the 120 limit, so at least +18%) |\n| Hunter's Dream, 1440p native, invariant positions (below) | 85.7 | **98.9** (+15%) |\n| M3 Pro 18 GB, compression off → on ([@MojahedAbushawish](https:\u002F\u002Fgithub.com\u002FMojahedAbushawish)) | 37.6 \u002F 49.7 \u002F 28.5 | **44.3 \u002F 62.2 \u002F 40.2** (+18% \u002F +25% \u002F +41%) |\n\nGPU time is what decides whether a slower Mac holds 60 FPS (16.7 ms per frame), so these gains\nmatter most on base and Pro chips. What changed:\n\n- **Lossless texture compression** (from [@MojahedAbushawish](https:\u002F\u002Fgithub.com\u002FMojahedAbushawish), #33).\n  Apple GPUs compress textures and render targets without any loss, but only when they are\n  created without two usage flags. Every texture had both, so nothing was compressed and memory\n  bandwidth was the largest cost of a frame. Textures now get those flags only when something\n  needs them. Launcher: Advanced → Performance → **Texture compression** (on; turn it off if you\n  see wrong colours or broken textures).\n- **Invariant positions instead of precise math in vertex shaders** (from Mojahed's #20). Positions\n  stay identical between passes through Metal's invariance, without the precise-math mode that\n  blocked the shader compiler's optimisations. The shader cache rebuilds once after updating.\n- **Vanishing floors, walls and props fixed** (found by [@DiAvisoo](https:\u002F\u002Fgithub.com\u002FDiAvisoo), #36; #35, #18).\n  Metal's indexed and indirect draws use only the low 32 bits of their buffer offset, on every\n  Apple GPU tested (M2 Max, M4 Max): when streaming placed a large mesh more than 4 GiB into the\n  game's GPU memory, the draw read the wrong data and the mesh disappeared until a reload. Such\n  draws now go through a second Metal buffer over the same memory, at a low offset, with no copy.\n- **Smoother full screen** (#25): three frame buffers instead of two in full screen, where macOS\n  shows the game's frames directly. Late frames per test run: 10–18 → 0–2.\n- **Native ultrawide** (from [@DiAvisoo](https:\u002F\u002Fgithub.com\u002FDiAvisoo), #30, building on Kyo's\n  resolution patches): 2560×1080 and 3440×1440 (21:9), 2560×720, 3840×1080 and 5120×1440 (32:9)\n  in the launcher, with the camera and HUD adjusted. 3840×1080 holds 60 FPS on an M4 Max; the\n  1440-tall modes need a lot of GPU memory, and the launcher warns on Macs with less than 24 GB.\n- **Optional frame pacing** (in-game menu: Display → Frame pacing): each frame stays on screen for\n  one period of the FPS cap, for even motion on ProMotion displays, at the cost of about one\n  frame of input latency. Off by default.\n- The pipeline archive is written less often while many new shaders appear (less competition with\n  the game on Macs with fewer cores).\n\n### New in 0.5.3: fixes, crash reports\n\n- **The black loading screen** (#18, found by Mojahed in #20) and **very low frame rates on 16 GB\n  Macs** with an upscaler or at 720p (#22, #19) are fixed.\n- **Crash reports:** the launcher shows what happened and opens a GitHub issue with the log.\n- **Advanced tab** in the launcher (#15); +5–15% FPS from deferred copies and 10–22% less CPU\n  (Mojahed's #20); MoltenVK and the Vulkan loader are gone from the app.\n\n### Benchmarks: 0.4.0 → 0.5.0\n\nApple M4 Max (48 GB), frame rate uncapped, FPS while standing still (30 s), 2026-10-17\u002F18. Each\ncell is mac-v0.4.0 (MoltenVK) → mac-v0.5.0 (native Metal); \"Quality\" upscales 1.5× (for example\n1280×720 → 1920×1080).\n\n| Scene | 1080p native | 1440p native | 1440p MetalFX Quality | 1440p TAA | 1080p FSR 3.1 Quality | 1440p FSR 3.1 Quality |\n|---|---|---|---|---|---|---|\n| Central Yharnam, first lamp | 97.5 → **97.7** | 66.2 → **75.1** | 95.1 → **95.7** | 61.9 → **69.9** | 117.0 → **119.5** | 95.6 → **98.0** |\n| Cathedral Ward | 103.2 → **104.8** | 72.0 → **82.7** | 99.5 → **102.3** | 67.0 → **78.3** | 122.0 → **126.6** | 98.8 → **108.6** |\n| Upper Cathedral Ward | 78.5 → **83.2** | 57.2 → **65.2** | 76.7 → **81.0** | 54.4 → **61.7** | 92.0 → **97.7** | 75.7 → **84.8** |\n| Hunter's Dream, headstone | 98.0 → **104.3** | 69.5 → **82.0** | 92.6 → **100.9** | 64.9 → **76.1** | 108.0 → **120.2** | 92.6 → **99.0** |\n\n0.5.0 is ahead in every case, by **12–18% at 1440p**. With the 60 FPS cap both hold a steady 60\n(every frame 16.7 ms). Uncapped, 0.5.0 occasionally has a single longer frame (20–40 ms) that\n0.4.0 does not; it does not occur with a frame cap (backlog).\n\n### From 22 to 120 FPS\n\nThe first playable build (2026-10-11) ran the first level at **~22 FPS** at native 1080p. What\ngot it to 60 and beyond, in order:\n\n| Version | Change | Effect |\n|---|---|---|\n| 0.3.0 | **MetalFX temporal upscaling** (via `VK_EXT_metal_objects`) alongside FSR 3.1 | Render at 720p, upscale to 1080p: 22 → ~30 FPS at the time |\n| 0.3.0 | **Native arm64 GPU process.** The game still runs as x86-64 under Rosetta 2, but all rendering moved into a separate native `bbgpu-host` process sharing the game's memory (Mach memory entry, ring buffers, cross-process page-protection relays) | MoltenVK's Vulkan→Metal encoding costs **1.75× less CPU** natively; now the default |\n| 0.3.0 | **Tiny render area for passes with no output.** ~20 vertex-only passes per frame were tiled over a 16384×16384 area | 27.5 → 33.9 FPS in the city |\n| 0.3.0 | **Upload hoisting.** Buffer uploads recorded ahead of the submission instead of splitting render passes | 33.9 → 34.8 FPS, fewer G-buffer pass splits |\n| 0.3.0 | **Pipeline cache kept between sessions.** It was wiped every launch (~500 shader compiles each session; the \"stutter when attacking\") | 2 compiles per session instead of ~500 |\n| 0.3.0 | **No \"precise\" float math in pixel\u002Fcompute shaders.** SPIR-V `NoContraction` became `[[clang::optnone]]` helper calls for every float operation in Metal (223 of 308 shaders) | City respawn spot **39 → 60 FPS**, GPU 19.6 → 12.1 ms per frame |\n| 0.3.0 | Shader permutation fix (Metal rejected ~6 pipelines per session, their draws vanished); unnamed pooled command buffers (MoltenVK labelled every encoder, ~4% CPU) | Correct image; less CPU per frame |\n| 0.3.0 | **Shaders compile on background threads** (4 low-priority threads). Option `shader_compile=wait` (brief hitch, complete image), `skip` (no hitch, an object may pop in) or `balanced` (default: waits up to 6 ms per frame, then skips) in `bbport.ini` and the in-game menu | Level load with an empty cache: render thread compile time 440 → 130 ms; worst frame 248 → 76 ms with `skip`. Walking into new areas with slow (cold) compiles: 15 frames frozen 120–190 ms with `wait`, one 41 ms frame with `balanced` |\n| 0.3.1 | **MoltenVK encodes while we record** (prefilled Metal command buffers) instead of encoding the whole frame inside the flip's submit (~13 ms) | Judder: late game frames **~6× fewer**; the \"solid 60\" feel |\n| 0.3.3 | **No Metal argument buffers in MoltenVK** (push descriptors bound directly; the tip came from [Huax-1839\u002Fbloodborne-macos](https:\u002F\u002Fgithub.com\u002FHuax-1839\u002Fbloodborne-macos)) | **+13–16%** everywhere: 1080p native 82 → 94, 1440p native 59 → 66 (above 60 for the first time), FSR\u002FMetalFX 92 → 107 |\n| 0.5.0 | **Native Metal renderer.** The video core encodes Metal directly (no Vulkan, no MoltenVK): untracked guest buffers with our own ordering, a pipeline archive kept between sessions, MetalFX on our own textures, FSR 3.1 through a Metal back end for AMD's FidelityFX interface | **1440p native 69.5 → 82.0**, FSR 3.1 Quality 1080p **108 → 120** (Hunter's Dream; table above) |\n| 0.5.3 | **Copies inside a render pass wait until it ends** (Mojahed, #20) | +5–7% at 1440p, up to +15% at 1080p |\n| 0.5.4 | **Invariant positions** instead of precise vertex math (Mojahed, #20) | Hunter's Dream 1440p **85.7 → 98.9** |\n| 0.5.4 | **Lossless texture compression** (Mojahed, #33) | Hunter's Dream 1440p **102 → 120** (cap); 4K native in Hemwick **51 → 70** together with the line above |\n\nAlso fixed along the way: a MoltenVK crash from two threads sharing one command pool, and\ngeometry corruption at 1440p (scenes above 1080p now use live resolution changes).\n\n### New in 0.5.2: 16 GB Macs, controller menu\n\n- **Less GPU memory, for 16 GB Macs** (#19). The game's GPU memory block is now 6 GB on every\n  Mac, sized to what the game actually uses (it was 8 GB on 16 GB Macs and up to 16 GB on larger\n  ones), and textures are budgeted around it. On 16 GB Macs the game sat right at macOS's GPU\n  memory limit, which can make it very slow. With a 16 GB Mac's limits simulated on an M4 Max,\n  peak GPU memory drops from ~11.5 GB to 9.6 GB at a steady 60 FPS.\n- **A possible fix for the black loading screen** (#18): the order of the game's compute\n  submissions could leave the GPU waiting on work that was never queued.\n- **The in-game menu works with a controller again.** L3+R3 opens it, the D-pad and\n  Cross\u002FCircle move around it, and the D-pad moves sliders such as Sharpness.\n- **The launcher can be turned back on from the game**: the in-game menu's Display tab has\n  \"Show the launcher when Bloodborne opens\".\n\n### New in 0.5.1: fixes\n\n- **macOS 27: the GPU process works again** (thanks to [Noel Miller](https:\u002F\u002Fgithub.com\u002Fnoelmiller)).\n  On macOS 27 the system's memory allocator takes addresses in the range the GPU process needs\n  before the program starts, so it fell back to running the game in one process. A second build\n  of the GPU process (`bbgpu-host-macos27`) reserves the range when macOS loads it; the game\n  starts it on macOS 27 and later only (earlier versions keep the existing one).\n- **Typing your character's name works in full screen** (thanks to Noel Miller): a box over the\n  game shows the prompt and what you type. Backspace deletes, Enter confirms, Esc cancels; the\n  name is exactly what you typed (an empty or cancelled entry no longer becomes \"Hunter\").\n  Password fields show dots.\n- **A game folder without the game's data is refused with an explanation** instead of crashing\n  (exit code 139): the 1.09 update on its own is not enough, the folder needs the whole base game\n  with the update copied over it.\n- The log's `GPU arena:` line says what decided the arena's size.\n\n### New in 0.5.0: native Metal\n\n- **A native Metal renderer replaces MoltenVK.** Faster in every scene and setting measured\n  (above), most at 1440p. MetalFX, FSR 3.1 (AMD's FidelityFX code on a Metal back end; its output\n  matches the Vulkan version bit for bit on test frames), TAA, FSR 1 (`BB_FSR1=1`), the settings\n  overlay and frame capture all run on it.\n- **Memory leak fixed (game process).** The game process grew about **4.5 GB per hour** of play\n  (2.5 → 6.2 GB in a 45-minute walk): freed small blocks of the runtime's allocator were filed\n  under the wrong size class. It now stays flat at about 2.5 GB.\n- **Macs with less memory** (thanks to [Noel Miller](https:\u002F\u002Fgithub.com\u002Fnoelmiller)): the GPU\n  memory arena is sized to the Mac (a quarter of its memory, 8 GiB minimum, 16 GiB at most);\n  a 16 GiB arena left the GPU waiting on a 36 GB Mac (~7 FPS). A rare freeze after long\n  sessions (two threads recording GPU commands at once) is fixed, touchpad touches behave like a\n  DualShock 4's, and a missing GPU hint no longer stops the game.\n- **Rendering fixes:** three full-screen passes that Metal refused are drawn (the light behind\n  the cage bars at the first lamp; the figure in the cage is back).\n- **Fallback:** if the GPU process cannot start, the game runs in one process on Metal (60 FPS\n  here).\n\n### New in 0.4.0: the launcher\n\n`Bloodborne.app` now opens a launcher window (native SwiftUI) before the game, like a Steam\nlauncher, with every setting on one screen (no scrolling, even on a 13\" MacBook Air):\n\n- **Display:** output resolution, windowed or full screen, frame rate cap (30, 40, 60, 90, 120).\n- **Upscaler:** off, MetalFX or FSR 3.1, its quality level, and the resolution the game\n  actually renders at (for example 1280 × 720 → 1920 × 1080); FSR sharpening.\n- **Effects:** depth of field, motion blur, chromatic aberration, ambient occlusion, shadows\n  from dynamic lights, screen-space reflections, the game's own anti-aliasing, the FPS counter,\n  and **skip intro videos** (straight to the title screen, no Sony and FromSoftware logos).\n- **Locations:** the game folder (checked before Play is enabled) and the save folder (it\n  offers to copy your saves to a new folder; the originals stay where they were).\n- **Show launcher every time:** untick it to start the game directly next time; hold **⌥\n  (Option)** while opening the app to get the window back.\n\nSettings are shared with the in-game overlay (`⌘,`) and stored in `bbport.ini`. When the game\nquits, the launcher comes back; if it stopped with an error, the launcher says so and offers\nthe log.\n\n### Earlier changes (0.3.x, 2026-10-14)\n\n- **Load crash fixed.** The intermittent crash while loading an area (the GPU window closing\n  during a loading screen) was a race in the game itself: the main thread records\n  cloth\u002Ftexture compute jobs into the render thread's command stream without a lock, and the\n  render thread's next loading-screen frame could start in the middle of them. On a PS4 the\n  main thread is done before the next vsync; under Rosetta it can take ~7 ms longer, more when\n  the Mac is busy. The port now hooks both game functions and makes them take turns (the main\n  thread waits well under a millisecond); in 15 test loads the race was caught 10 times and\n  never corrupted anything. As a safety net, corrupted GPU commands are logged and skipped\n  instead of ending the game.\n- **Sharper on Retina displays:** the window uses the display's real pixels (full screen on a\n  MacBook was rendered at half resolution and stretched).\n- **Full screen works** (⌃⌘F or the green window button). It used to freeze the picture.\n- **Lower display latency:** two swapchain images instead of three, so the time from the\n  game presenting a frame to it reaching the screen went from 48.5 to 31.7 ms.\n- **Game file reads no longer fail** when they land in memory the GPU is watching. macOS\n  failed such reads outright, so the game could lose an asset load; a possible cause of the\n  missing-geometry reports below.\n- **Shader compile mode `balanced`** is the default: new shaders compile in the background\n  and a frame waits at most 6 ms for them, so new areas no longer freeze for 100+ ms.\n- **Less judder:** late game frames (the cause of judder at a steady 60) dropped about 6x with\n  the upscaler off or FSR: MoltenVK now encodes each frame's Metal commands while they are\n  recorded instead of all at once at the flip, which the game was waiting behind.\n- **Diagnostics:** `BB_FRAME_STATS=1` prints per-stage timings of every late frame (\"Spike\"\n  lines, with each game thread's CPU time), and corrupted GPU command streams are reported\n  with the game threads and code involved.\n\n### Known issues\n\n- **Missing geometry:** floors, walls and props vanishing until a reload (Metal's 32-bit index\n  offsets) are fixed in 0.5.4, and trees and other instanced tessellated objects that never drew\n  (Forbidden Woods, #35) in 0.5.4.1. If something still goes missing, reports with a screenshot\n  and `game.log` are welcome on #35.\n- **Occasional judder at a steady 60 FPS** (some game frames take 20–45 ms): much rarer since\n  2026-10-15 (about 6x fewer late frames).\n- **Uncapped, an occasional single long frame** (20–40 ms) on the Metal renderer; capped play\n  (60\u002F90\u002F120) is not affected.\n- **Above 1080p, the selected item's icon in the HUD is missing** (an empty frame; #14). It is\n  there at 1080p.\n- **At 16:10, full-screen menus keep their 16:9 artwork** (grey bars at the sides), and the first\n  moments of loading a level can glitch. The HUD itself is placed correctly. A UI mod such as\n  \"16x10 and 4x3 UI Fixes\" (Nexus Mods) fixes the menus and loads through **Mods & Cheats…**.\n\n### What's next\n\n- **Fewer Metal render passes.** In Central Yharnam, tessellated draws split the render pass\n  67 times a frame (372 Metal encoders per frame); skipping tessellation altogether as an upper\n  bound saves 1–2 ms of GPU time per frame (6.6–7.5 → 5.6 ms). Keeping those draws inside the pass is next\n  (Mojahed's #39 starts on it).\n- **0.6:** MetalFX frame generation (#64), as pre-releases first. Online co-op (#9) after that.\n- A faster, more direct mouse camera.\n- Confirm the missing-geometry fix on more Macs; the frame-time judder.\n- Signing and notarisation of the downloadable app (today it must be released from quarantine).\n\nDetails:\n- Roadmap (released, next, later): [docs\u002FROADMAP.md](docs\u002FROADMAP.md)\n- Plan, design decisions and porting checklist: [docs\u002FMACOS_PORT.md](docs\u002FMACOS_PORT.md)\n- Known issues and planned refinements: [docs\u002FMACOS_BACKLOG.md](docs\u002FMACOS_BACKLOG.md)\n- Every test and measurement: [docs\u002FFINDINGS.md](docs\u002FFINDINGS.md)\n- The two-process design: [docs\u002FDESIGN_NATIVE_GPU_PROCESS.md](docs\u002FDESIGN_NATIVE_GPU_PROCESS.md)\n\n## How it works\n\n- **Native execution under Rosetta 2.** The eboot is converted offline into a flat memory\n  image; PS4 libc and libSceFios2 functions are linked directly into it. There is no CPU\n  emulation layer of our own — Rosetta 2 translates the x86-64 code (game + runtime) once.\n  The build targets `x86_64-apple-macos` with deployment target 15.0 (Rosetta AVX2 support).\n- **HLE runtime** (`src\u002F`): kernel, memory, threads, audio, input (SDL3), save data and other\n  PS4 libraries. macOS specifics: guest TLS via a reserved pthread TSD slot, guest-visible\n  memory kept below 1 TiB, Mach-based thread inspection.\n- **GPU** (`gpu\u002F`): the shadPS4 video core and shader recompiler, built as\n  `libbbgpu.dylib`, rendering through native Metal (`renderer_metal\u002F`). It runs in\n  `bbgpu-host`, a **native arm64 process** that maps the game's memory at the same addresses\n  (`host\u002F`, `docs\u002FDESIGN_NATIVE_GPU_PROCESS.md`). If it cannot start, the game stops with a\n  \"Crash:\" line that the launcher shows in a crash report.\n- **Upscalers:** MetalFX temporal upscaling, FSR 3.1 (AMD FidelityFX on a Metal back end,\n  `gpu\u002Fshim\u002Fffx_metal\u002F`) and TAA. Planned: zero-copy guest memory on unified memory.\n- Inherited from upstream: high-frame-rate community patches, synthetic motion vectors and\n  temporal upscaling (FSR 3.1), a two-stage multi-threaded draw pipeline, and an in-game\n  settings overlay (`⌘,` or `L3 + R3`; L3 + R3 can be turned off on the Controls page).\n\n## Download (no building needed)\n\nReady-made builds are attached to the [releases](https:\u002F\u002Fgithub.com\u002FWooloomooloo2\u002Fbloodborne_mac_port\u002Freleases)\nas `Bloodborne-macOS-\u003Cversion>.zip` (about 50 MB). It needs an Apple Silicon Mac with macOS 15\nor newer and **at least 16 GB of memory**. You still need **your own game dump** (see below): no\ngame files are included.\n\n1. Unzip it and move **`Bloodborne.app`** to Applications (or anywhere).\n2. **Release it from quarantine.** The app is not signed with an Apple developer certificate,\n   so macOS blocks downloaded copies (\"Apple could not verify…\"). Either run, in Terminal:\n\n   ```sh\n   xattr -dr com.apple.quarantine \u002FApplications\u002FBloodborne.app\n   ```\n\n   or open it once, then go to **System Settings → Privacy & Security** and click\n   **Open Anyway** next to the Bloodborne message.\n3. Open it. The launcher window opens: under **Locations**, choose your game folder (the\n   `CUSA03173` folder containing `eboot.bin`); it is checked, and **Play** is enabled once it\n   passes. Pick your settings and press Play. If Rosetta 2 is missing, it offers to install it.\n\nThe app contains everything else (the game process, the native GPU process, the libraries and\na small Python for the launch scripts). Saves and settings go to\n`~\u002FLibrary\u002FApplication Support\u002FBloodborne` (another save folder can be chosen in the launcher),\nthe logs to `~\u002FLibrary\u002FLogs\u002FBloodborne` (see [Logs](#logs)). To change the game folder, use the launcher's\n**Locations** (hold ⌥ while opening the app if the launcher is set not to show).\n\n**Updates.** The first time it opens, the app asks whether to check for updates automatically\n(also when the launcher window is turned off, before the game starts). If you agree, the launcher\nchecks the GitHub releases once a day and offers a newer version with its release notes: when its\nwindow opens, or, with the window turned off, in the background while you play, showing the update\nafter the game ends. **Install\nUpdate** downloads it, checks it (size, SHA-256 from GitHub, bundle identifier, version, code\nsignature), replaces `Bloodborne.app` where it is and opens it again; saves and settings are not\ntouched. **Bloodborne → Check for Updates…** checks at once; the update window has the\n*Check for updates automatically* and *Include test builds* (pre-releases and `mac-v…-test1`\ntags) options. The\napp must be somewhere you can write (Applications is fine) and not run from the Downloads quarantine\nlocation. **Bloodborne → About Bloodborne** shows the version, build and commit.\n\n**Preparing the game folder from PKG files.** The app needs an unpacked folder, not `.pkg`\nfiles. If you already play on shadPS4 you have one: use that folder, but first copy the\ncontents of the update folder next to it (`CUSA03173-patch` or similar) into it, replacing\nfiles. To unpack decrypted (fake-signed) PKGs, download `pkg_extract-macOS.zip` from the same\nrelease, unzip it and, in Terminal from that folder:\n\n```sh\nxattr -d com.apple.quarantine pkg_extract\n.\u002Fpkg_extract \u002Fpath\u002Fto\u002Fbase-game.pkg ~\u002FBloodborne        # creates ~\u002FBloodborne\u002FCUSA03173\n.\u002Fpkg_extract \u002Fpath\u002Fto\u002Fupdate-1.09.pkg ~\u002FBloodborne-update\nditto ~\u002FBloodborne-update\u002FCUSA03173 ~\u002FBloodborne\u002FCUSA03173   # merge the update over the game\n```\n\nRetail PKGs (from the PlayStation Store or a disc install) are encrypted with console keys and\nmust be dumped on a jailbroken PS4 first; no Mac tool can unpack them.\n\n**The game files must be the original 1.09 executable.** A pre-patched `eboot.bin` (for\nexample a 60 FPS patch made for jailbroken consoles) is rejected: this port applies its own\n60 FPS patches in memory at start, so use the unmodified `eboot.bin` from the 1.09 update.\n\n## Requirements (building from source)\n\n- A Mac with **Apple Silicon** running **macOS 15 or newer**, with at least **16 GB** of memory\n- **Rosetta 2** (`softwareupdate --install-rosetta`)\n- **Xcode Command Line Tools** (`xcode-select --install`)\n- **Homebrew** (arm64) with build tools:\n  `brew install cmake ninja nasm glslang pkgconf boost cryptopp`\n- **Python 3** (patch compiler and eboot preparation scripts)\n- **Your own decrypted game dump**: a `CUSA03173` folder (v1.09) containing `eboot.bin`,\n  `sce_sys\u002F`, `sce_module\u002F` and `dvdroot_ps4\u002F`. `python3 scripts\u002Fgame_check.py` verifies it.\n\n## Building\n\n```sh\ngit clone --recursive https:\u002F\u002Fgithub.com\u002FWooloomooloo2\u002Fbloodborne_mac_port.git\ncd bloodborne_mac_port\n\n# 1. Build pinned dependencies (SDL3, FFmpeg, SPIRV-Cross, Vulkan-Headers, ...) into deps\u002F:\n#    x86-64 for the game process, arm64 for the native GPU host (once)\nbash scripts\u002Fmacos\u002Fbootstrap_deps.sh\nBB_DEPS_ARCH=arm64 bash scripts\u002Fmacos\u002Fbootstrap_deps.sh\n\n# 2. Build the loader, the GPU library and the GPU host\n#    (out\u002Fbb-probe, out\u002Fgpu\u002Flibbbgpu.dylib, out\u002Fbbgpu-host)\nbash build_macos.sh\n```\n\nLaunching rebuilds whatever changed, so after a `git pull` you can simply launch again.\n\n## Launching\n\n### As a Mac app (no Terminal window)\n\nOnce, in Terminal from the repository folder:\n\n```sh\nbash scripts\u002Fmacos\u002Fmake_app.sh\n```\n\nThis creates **`Bloodborne.app`** in the repository folder, with the game's own icon (taken from\nyour game folder, so the app is made on your Mac and never uploaded). Double-click it, or drag\nit to the Dock. It opens the same launcher window as the downloadable app (settings, game and\nsave folders; see \"New in 0.4.0\" above), runs the game from this checkout without a Terminal\nwindow, and writes the game's logs to `~\u002FLibrary\u002FLogs\u002FBloodborne` (see [Logs](#logs)). If the\ngame stops with an error, the launcher offers a crash report and the log. Run the\nscript again if you move the repository folder. Its update check only tells you about new releases: update a\ncheckout with `git pull` and build again.\n\n### From Finder with a Terminal window\n\nDouble-click **`Bloodborne.command`** in the repository folder. It opens a Terminal window and\nstarts the game, with its log in that window.\n\n- **First launch:** it asks for your game folder (the `CUSA03173` folder containing\n  `eboot.bin`) and remembers it in `launch.conf` next to it. If the game folder sits next to the\n  repository (`..\u002FCUSA03173`), it is found without asking.\n- **Keep the Terminal window open** while you play: closing it ends the game. The game's log\n  appears there, and if the game exits with an error the window stays open so you can read it.\n- macOS may ask you to allow Terminal to access the folder the game is in (Desktop, Documents,\n  an external drive): allow it.\n- To put it in the Dock or on the Desktop, ⌥⌘-drag `Bloodborne.command` there to make an alias.\n- If macOS refuses to open it (\"cannot be opened because it is from an unidentified\n  developer\"; this happens if the repository was downloaded as a zip rather than cloned),\n  right-click it, choose **Open**, then **Open** again. If it says you lack permission, run\n  `chmod +x Bloodborne.command` once.\n\n`launch.conf` holds shell assignments and is not committed. Besides the game folder it can set\nany other `run.sh` variable, such as `BB_DATA_DIR` (below):\n\n```sh\nBB_GAME_DIR=\u002FUsers\u002Fyou\u002FBloodborne\u002FCUSA03173\n```\n\n### Saves and settings\n\nSaves, settings (`bbport.ini`) and shader caches live in\n**`~\u002FLibrary\u002FApplication Support\u002FBloodborne`**. The **`Saves`** shortcut in the repository folder\nopens the save folder in Finder; your character is in `1\u002FCUSA00207\u002FSPRJ0005\u002F` (the PS4's own\nsave layout, so saves can be copied to and from the Linux and Windows ports). Quit the game\nbefore copying saves.\n\nTo keep them elsewhere, set `BB_DATA_DIR=\u002Fsome\u002Ffolder` in `launch.conf` (or the environment).\nA checkout that already has saves in its own folder (`user\u002F`, from before this default) keeps\nusing them; move `user\u002F` and `bbport.ini` to the folder above to switch.\n\n### Mods and cheats\n\n**Mods & Cheats…** at the bottom left of the launcher opens the mod manager. The text next to the\nbutton shows what's on (\"No mods or cheats\", \"2 mods · 1 cheat on\").\n\n- **Mods** are folders in `~\u002FLibrary\u002FApplication Support\u002FBloodborne\u002Fmods` (**Open Mods Folder**).\n  A mod can hold `dvdroot_ps4\u002F`, or the game's own top-level folders (`chr\u002F`, `parts\u002F`, ...),\n  optionally inside one wrapper folder. **Add Mod…** takes a folder or a .zip and checks its layout\n  straight away.\n  - Mods later in the list win when two replace the same file. The **Conflicts** list shows each\n    case.\n  - Each launch gets a private merged view of the game made of links. Your game folder and the\n    mod folders are never written to.\n  - Replacements for `eboot.bin`, `sce_module` and `sce_sys` are refused.\n  - The order and switches are saved in `mods.json`. [docs\u002FMODS.md](docs\u002FMODS.md) has the folder\n    rules.\n- **Cheats & Tweaks** are patches from the community patch file (`patches\u002FBloodborne.xml`), each\n  with its own note. Pairs that do opposite things switch each other off: rally decay or no rally,\n  lighter or heavier corpse physics. The choices are stored as `cheats=` in `bbport.ini`. *Enemy\n  Control* is not offered: it rewrites the same code as the frame-rate patches.\n- **Patch Files** lists `.xml` patch files you put in `~\u002FLibrary\u002FApplication\n  Support\u002FBloodborne\u002Fpatches`, each with an on\u002Foff switch.\n- **Save backups:** before the first launch with a set of mods or cheats it hasn't seen,\n  **Play** copies your save folder to `save-backups\u002F\u003Cdate and time>\u002F`, keeping the newest five.\n  Other folders in `save-backups` are never touched.\n\n### Benchmark\n\n**Benchmark…** in the launcher starts the game twice with its own save and settings, about 6\nminutes in all. Your save and settings are not used or changed, and mods, patch files and cheats\nare off, so results from different Macs compare like for like.\n\n1. **Traversal:** a recorded walk through Central Yharnam at 1080p, capped at 60 FPS. New areas\n   stream in and new shaders compile on the way, so this pass shows traversal stutter.\n2. **Throughput:** 30 seconds standing still, uncapped, for the highest frame rate the Mac\n   reaches.\n\nThe results window shows, for each pass:\n\n- average and best FPS, 1% and 0.1% lows, the longest frame;\n- frames over 33, 50 and 100 ms, and milliseconds lost to hitches per minute;\n- the worst hitches with their time on the route and likely cause;\n- GPU busy time, shader compiles, the game's CPU use and memory, swap, memory pressure and thermal\n  state.\n\nEach run is kept in `~\u002FLibrary\u002FLogs\u002FBloodborne\u002FBenchmarks\u002F\u003Cdate and time>\u002F`:\n\n- `report.md` (the same text, ready to paste into an issue) and `summary.json`;\n- a per-frame CSV for each pass, `system.csv`, and each pass's game log.\n\nPlease run it when you are reporting a performance problem. The benchmark's own save (a character\nin Central Yharnam with the route cleared of enemies) and the recorded route are in `benchmark\u002F`\nand inside the app; your own saves are never used.\n[docs\u002FDESIGN_BENCHMARK.md](docs\u002FDESIGN_BENCHMARK.md) has the details.\n\n### Logs\n\nEach game session started from the launcher writes two logs to **`~\u002FLibrary\u002FLogs\u002FBloodborne`**,\nnamed by the time it started. The last 20 sessions are kept, at most 256 MB in all, and one\nsession's logs stop at 64 MB (a normal session is well under 1 MB): past that only its last\n1,000 lines are written, when the game ends, after a line saying how many were left out.\n\n- `game-2026-10-22_14-03-05.log`: the game's output, each line with its time and a syslog\n  severity (`CRIT`, `ERROR`, `WARN`, `NOTICE`, `INFO`, `DEBUG`):\n\n  ```text\n  2026-10-22T14:03:05.869+03:00 NOTICE launcher: Bloodborne for Mac 0.5.4 on Mac15,8 (Apple M3 Max), 64 GB, ...\n  2026-10-22T14:03:06.284+03:00 WARN   GPU [Render.Vulkan] \u003CWarning> vk_pipeline_serialization.cpp:369 ...\n  2026-10-22T14:09:41.604+03:00 CRIT   Crash: the GPU process crashed (signal 11 in ...)\n  ```\n\n- `game-2026-10-22_14-03-05.jsonl`: the same lines as JSON, one object per line, for Grafana Loki\n  (Alloy\u002FPromtail), Elasticsearch (Filebeat), Vector and similar: `@timestamp` (UTC),\n  `log.level`, `syslog.severity.code`, `log.logger` (who wrote the line: `runtime`, `bbgpu-host`,\n  `gpu.render.vulkan`, ...), `message`, `session.id` and `service.version`.\n\n`game.log` and `game.previous.log` link to the last two sessions' `.log` files. Warnings and\nerrors also go to the macOS system log (unified logging), with the line's source as its category:\nopen **Console.app** and search for `bloodborne-mac-port`, or in Terminal:\n\n```sh\n\u002Fusr\u002Fbin\u002Flog stream --predicate 'subsystem == \"io.github.wooloomooloo2.bloodborne-mac-port\"'\n```\n\nThe game never depends on the logs: if the launcher quits or a log can't be written (a full\ndisk), the game keeps running and only those lines are lost.\n\nThe severity is read from the line itself: `Crash:` lines are critical, `STOP:` and `ERROR:` lines\nerrors, the GPU library's own levels (`\u003CWarning>`, `\u003CError>`) are kept, and lines saying something\nfailed are warnings. Your home folder appears as `~` in the system log and in crash reports.\n\n**Crash reports.** When the game stops with an error, the launcher shows what happened and, by\nitself, puts a diagnostics zip in `~\u002FLibrary\u002FLogs\u002FBloodborne\u002FReports` (the last 10 are kept): the\ncrash report, the session's `.log` and `.jsonl`, `bbport.ini`, `launch.conf`, and macOS's own\ncrash reports (`.ips`) of the game's processes from that session. Their exception and crashed\nthread also go into the report. Your home folder is shown as `~`, and the identifiers macOS puts\nin `.ips` files (crash reporter key, sleep\u002Fwake and boot session ids) are removed. Other paths\nstay as they are: a game folder on an external drive shows as `\u002FVolumes\u002F\u003Cdrive name>\u002F...`, so\ncheck the report if a drive or folder name is private. **Report on\nGitHub** opens a new issue with the report already filled in (copied to the clipboard as well,\nfor reports too long for the link) and shows the zip in Finder to drag onto the issue. Nothing is\nsent until you submit the issue.\n\n### Typing text\n\nText the game asks for (the character's name, the network password under *Network Settings*)\nis typed on the keyboard: a box over the frame shows the prompt and the text (as dots for the\npassword), Backspace deletes, Enter confirms, Esc cancels and leaves the field as it was. The\nfield gets exactly what was typed; the game's own length limit applies (the log line\n`ImeDialog opened (..., up to N chars)` shows it).\n\n### From Terminal\n\n```sh\ncd bloodborne_mac_port\nBB_GAME_DIR=\u002Fpath\u002Fto\u002FCUSA03173 bash run.sh\n```\n\n`run.sh` prepares the game image and rebuilds anything whose sources changed. It uses the same\nsaves and settings as the Finder launcher.\n\n### In the game\n\n- **Settings overlay:** `⌘,` (or L3 + R3 on a controller): FPS, resolution, upscaler (MetalFX,\n  FSR 3.1 or off), shader compile mode. Some changes need a restart. The launcher shows the\n  same settings before the game starts.\n- **Full screen:** ⌃⌘F or the green window button.\n- **Input:** game controllers (through SDL), the keyboard, and the mouse for the camera (turn on\n  **Mouse camera**). The launcher's **Controls** page rebinds keys, mouse buttons and the wheel\n  (two slots per action, a walk key) and sets the mouse speed; changes apply at the next start.\n- **First launch and new areas** compile shaders, so the first minutes stutter a little; later\n  sessions load them from the cache at start. The first launch after a rebuild takes ~20 s to\n  open the window.\n\n## Repository layout\n\n| Path | Contents |\n|---|---|\n| `src\u002F` | Loader (`probe.c`) and PS4 HLE runtime |\n| `gpu\u002F` | shadPS4-derived video core with the native Metal renderer, draw pipeline, upscalers |\n| `host\u002F` | Native arm64 GPU host process (`bbgpu-host`) and the shared rings |\n| `scripts\u002F` | Eboot preparation, linking, patch compiler (`patches.py`); `scripts\u002Fmacos\u002F` dependency bootstrap |\n| `patches\u002F` | Community XML patches for Bloodborne 1.09 |\n| `Bloodborne.command` | Finder launcher (runs `run.sh` in Terminal) |\n| `scripts\u002Fmacos\u002Fmake_app.sh` | Builds `Bloodborne.app`, a launcher without a Terminal window (local, not committed) |\n| `scripts\u002Fmacos\u002Fpackage_app.sh` | Builds the self-contained `dist\u002FBloodborne.app` and its zip for releases (CI: `.github\u002Fworkflows\u002Fmacos-release.yml`) |\n| `Saves` | Shortcut to the save folder (created on first launch, not committed) |\n| `launcher\u002F` | The macOS launcher window (Swift: `Model\u002F` with tests, `App\u002F`; built by `scripts\u002Fmacos\u002Fbuild_launcher.sh`) |\n| `tools\u002F` | Developer utilities, including `pkg_extract` (fpkg unpacker) |\n| `docs\u002F` | macOS plan and backlog, plus technical notes inherited from upstream |\n\n## Credits\n\nThis port stands entirely on the work of others:\n\n- **deadinside28** — author of `bbport`, the original native Linux port of Bloodborne: the flat memory image approach, the HLE\n  runtime, the two-stage Vulkan draw pipeline, synthetic motion vectors and the upscaler\n  integration.\n- **Mrsuss60** — [bloodborne_pc_windows_port](https:\u002F\u002Fgithub.com\u002FMrsuss60\u002Fbloodborne_pc_windows_port),\n  the Windows port this repository was forked from, including its stability, audio, memory\n  and frame-pacing fixes (documented in that repository's `CHANGES.md`).\n- **Paleblood contributors** — system-module argument validation evidence from\n  [Paleblood, branch `codex\u002Fruntime-sysmodule-wire`](https:\u002F\u002Fgithub.com\u002Fevill33t\u002FPaleblood\u002Ftree\u002Fcodex\u002Fruntime-sysmodule-wire),\n  commit `f9c5e5556db987d9fb4fa60b837d8a54817a0718`; provenance and limits in\n  [`docs\u002FSYSMODULE_WIRE.md`](docs\u002FSYSMODULE_WIRE.md).\n- **[shadPS4](https:\u002F\u002Fgithub.com\u002Fshadps4-emu\u002FshadPS4)** project — the Vulkan video core and\n  shader recompiler (`gpu\u002Fshadps4\u002F`, GPL-2.0-or-later).\n- **FireBurn** — [FSR-Vulkan](https:\u002F\u002Fgithub.com\u002FFireBurn\u002FFSR-Vulkan), the native Vulkan\n  FSR 3.1 \u002F FSR 4 runtime the port used until 0.5.0; FSR 3.1 is still built from its AMD\n  FidelityFX SDK sources (MIT).\n- **Omar Cornut** — [Dear ImGui](https:\u002F\u002Fgithub.com\u002Focornut\u002Fimgui), used for the in-game overlay (MIT).\n- **Alex Barney (Thealexbarney)** — [LibAtrac9](https:\u002F\u002Fgithub.com\u002FThealexbarney\u002FLibAtrac9),\n  AT9 audio decoding (MIT).\n- **sirit** — SPIR-V emitter used by the shader recompiler (BSD-3-Clause), with Khronos\n  **SPIRV-Headers** (MIT-style Khronos license).\n- **Christian Rau** — [half](https:\u002F\u002Fhalf.sourceforge.net\u002F), IEEE 754 half-precision\n  library (MIT).\n- **AMD** — GCN PM4\u002Fregister headers in `gpu\u002Fthird_party\u002Fgcn\u002F` (MIT-style AMD license).\n- **DejaVu fonts** (Bitstream Vera license) — overlay font.\n- **[MoltenVK](https:\u002F\u002Fgithub.com\u002FKhronosGroup\u002FMoltenVK)** (Apache-2.0), which ran the renderer\n  until 0.5.0, and the dependencies built by `scripts\u002Fmacos\u002Fbootstrap_deps.sh`: SDL3,\n  Vulkan-Headers, SPIRV-Cross, fmt, xxHash, miniz, FFmpeg, magic_enum, robin-map, Boost.\n- **Community patch authors** — Kyo, Lance McDonald, illusion, emoose, auser1337 and others\n  for the 60 FPS, camera and engine patches in `patches\u002FBloodborne.xml`.\n- **zackcage6** — testing and bug reports for the Windows port.\n\n### Contributors to this port\n\nThank you to everyone who sent pull requests:\n\n- **[Noel Miller](https:\u002F\u002Fgithub.com\u002Fnoelmiller)**\n  - macOS 27 support for the GPU process (#7).\n  - A survivable GPU setup warning (#10).\n  - Touchpad gestures (#8).\n  - Buffer arena sizing for Macs with less memory (#13).\n  - The HUD item icon above 1080p (#17).\n  - Online play (#9, in progress).\n  - Survivable co-op renderer stops (#11).\n- **[Mojahed Abushawish](https:\u002F\u002Fgithub.com\u002FMojahedAbushawish)**\n  - Lossless texture compression (#33).\n  - The upscaler haze fix (#48).\n  - Invariant vertex positions, copies held to the end of a render pass, and the loading-screen fix\n    (from #20).\n  - Mouse look (#20).\n  - Guest memory mapped in runs for 16-18 GB Macs (#85, #86).\n  - Benchmarks on an M3 Pro.\n- **[DiAvisoo](https:\u002F\u002Fgithub.com\u002FDiAvisoo)**\n  - Native ultrawide (#30).\n  - Duplicate-launch and game-folder checks (#28).\n  - The disappearing-geometry finding (#36).\n  - Audio dropout diagnostics (#32).\n  - The launcher's Stop button (#31).\n- **[satperm](https:\u002F\u002Fgithub.com\u002Fsatperm)**\n  - The About panel and update check (#23).\n  - Dated session logs and crash reports (#40).\n- **[soulripper13](https:\u002F\u002Fgithub.com\u002Fsoulripper13)**: the game's icon in the Dock (#66).\n- **[evill33t](https:\u002F\u002Fgithub.com\u002Fevill33t)**: PS4 runtime safety fixes (#80, #81, #82), the\n  long-session crash guards (#100, #114), stale descriptor hardening (#98), the GPU watchdog\n  fix (#107), and MetalFX frame\n  generation (#64, in progress).\n\nThanks also to everyone who reports issues and tests builds on their Macs. Reports, logs and\nmeasurements that shaped recent releases came from @noelmiller, @MojahedAbushawish, @DiAvisoo,\n@satperm, @IlyaDylko (keyboard sprint #61, long-session FPS #55), @wgorecodes (stuck game #71,\npreferred display #60), @Frosty2804 (16:10, #75), @lifeos-creator (M3 Pro, #53\u002F#69, tested 0.5.9; the updater, #96), @Sah-D (#47),\n@ulhaas, @Ohaq2108 and @rozenstein94 (the opening-movie freeze, #46), @khhan0703 (the opening-movie crash, #84, tested 0.5.9), @Didjus (#18),\n@PensionPlanning (#19), @muharremsedona6034gm-hub (#22), @Walltor (#25), @AmberUpraity,\n@VanDung-dev, @douglasrlee, @jefer9011 and @mariuszparowa666 (GPU stalls, fixed in 0.5.4.2),\n@zhouhaoyaomei-ship-it, @SimonKabb and @juliotwo (the memmove crash, fixed in 0.5.5), @ELLDev\nand @GChaucer (the GPU crash in fights, #74), @brewboi (5120×2160 and the cursor, #93), @danielsirbubusiness (#83, tested 0.5.9), @g3rro333333333, @rwv7p56n9s-cmyk, @LICHTYYYVVV and @vtsilva77.\n\nEach third-party component keeps its own license file in its directory.\n\n## License\n\nGNU General Public License v2.0 or later (GPL-2.0-or-later), because of the shadPS4\ncomponents. See [LICENSE](LICENSE).\n",2,"2026-10-31 04:26:29","CREATED_QUERY"]