Move OS text measurement off the logic thread, rework the credits window to avoid hitches, optimize bg-dynamics sprite mesh indexing, and fade audio out before iOS/tvOS suspend.

Author: efroemling

.efrocachemap

@@ -1,4 +1,4 @@
-### 1.8.0 (build 22997, api 9, 2026-08-22)
+### 1.8.0 (build 22998, api 9, 2026-08-24)
 - Fully implemented asset packages (more on this soon)
 - App-config committing (dirty-tracking, debounced disk writes, and
   suspend/shutdown flushes) now lives fully in `babase` instead of routing
@@ -113,6 +113,10 @@
   divisible by 4).
 - Android builds should now properly respect camera cutouts and round corners.
   Please holler if you see any UI elements being cut off at this point.
+- OS Text rendering (Asian languages, emoji, etc.) is now more efficient and
+  renders more cleanly in the background, meaning it should never cause frame
+  hitches. The credits window used to be a major offender here and should now
+  come up smoothly.
 
 ### 1.7.63 (build 22870, api 9, 2026-06-08)
 - Fixed mouse-wheel zooming in manual camera mode.

CHANGELOG.md

@@ -49,7 +49,8 @@ calls three `from_swift` entry points — `SetAppActive(bool)`, `SuspendApp()`,
 - **running** (`sceneWillEnterForeground` / `sceneDidEnterBackground`, the
   analogue of Android onStart/onStop) → `UnsuspendApp()` / `SuspendApp()`.
   `SuspendApp` parks all event-loop threads; the audio thread's suspend
-  callback calls `alcDevicePauseSOFT`, which is what actually stops audio.
+  callback fades master volume out and then calls `alcDevicePauseSOFT`,
+  which is what actually stops audio (see "Audio around suspend" below).
   The `CADisplayLink` is also paused
   (`UIKitGLViewController.setRenderingPaused`) so no GPU work happens in the
   background.
@@ -71,6 +72,34 @@ boot; the iOS shell avoids that.)
 
 Files: `app_platform/apple/{from_swift.h,from_swift.cc,UIKitSupport.swift,UIKitSceneDelegate.swift,UIKitGLViewController.swift}`.
 
+## Audio around suspend
+
+`alcDevicePauseSOFT` is a hard stop: it stops the CoreAudio unit
+immediately, so before 2026-08-22 backgrounding cut whatever was playing
+off mid-waveform at full amplitude. On iOS that lands right as the OS is
+tearing down our audio session, and the result sounded like a moment of
+corrupted audio rather than a clean stop.
+
+`AudioServer::FadeMasterGainForSuspend_` therefore ramps OpenAL's master
+(listener) gain to silence over 120ms and lets the mixer run on that
+silence for another 60ms *before* pausing the device, then ramps back up
+after unsuspending. It early-outs when nothing audible is playing, so it
+only costs time when it buys something. Budget-wise this is fine: a
+measured suspend with music playing completes in ~211ms against
+`SuspendApp`'s 4s cap (and Apple's ~5s background deadline).
+
+Two related facts worth knowing before touching this:
+
+- **Nobody in the process owns the `AVAudioSession`** — not our code, and
+  not the OpenAL Soft xcframework (it links AudioToolbox/CoreAudio, no
+  AVFAudio). So we run on the implicit default category, never explicitly
+  activated, with no interruption handler, and the system's session
+  teardown races our own `AudioOutputUnitStop`. The fade hides the
+  symptom; owning the session would remove the race. See `followups.md`.
+- **Listener gain is otherwise unused** by the engine (only
+  position/velocity/orientation are set), which is why it's available as
+  a master knob here.
+
 ## Input
 
 - **Touch:** `UIKitGLViewController` overrides
@@ -181,6 +210,56 @@ platform-specific pieces worth knowing:
   --predicate 'subsystem == "net.froemling.ballistica"'` (or `log stream`).
   Note `simctl launch --console[-pty]` does *not* capture the sim app's
   stderr — os_log is the reliable channel.
+- **`LowLevelDebugLog` goes nowhere on Apple.** `HandleLowLevelDebugLog`
+  is only overridden on Android (crash-log breadcrumbs); the base impl in
+  `platform.cc` is empty. So calls like the `"Calling alcDevicePauseSOFT
+  at ..."` breadcrumbs in `audio_server.cc` are invisible here — don't
+  plan an iOS investigation around grepping for one. Use a real logger.
+- **Exercising background/foreground in the Simulator**: background the
+  app by launching another one (`xcrun simctl launch booted
+  com.apple.Preferences`), then foreground it with `xcrun simctl launch
+  booted <our-bundle-id>` — that resumes the existing process rather than
+  relaunching (same pid back), so it exercises the real
+  suspend/unsuspend path. Pair with `--log 'ba=DEBUG'` to get
+  `SuspendApp() completed in Nms.` / `UnsuspendApp() completed in Nms.`,
+  which are logged on `LogName::kBa` at DEBUG in debug builds only.
+- **`make ios` / `make tvos` device pick** (impl: lifecycle in
+  `tools/batools/iossim.py`; pcommands `ios_sim_run` / `ios_sim_log` in
+  `tools/batools/pcommands4.py`). Order, no config needed:
+  `IOS_SIM_DEVICE` override (name or udid) → reuse an already-booted
+  device → the Simulator app's `CurrentDeviceUDID` (`defaults read
+  com.apple.iphonesimulator`) → newest available, booted on demand. The
+  `CurrentDeviceUDID` step matters: `open -a Simulator` auto-boots the
+  app's last-used device, so a disagreeing pick yields TWO sim windows.
+  Booting is async — always `simctl bootstatus -b` before install, and
+  boot BEFORE opening Simulator.app (opening first races the auto-boot
+  → "Unable to boot device in current state: Booted").
+
+### Testing the software keyboard in the Simulator
+
+Verifying anything keyboard-related needs setup the sim fights you on
+(cost ~20 min on 2026-08-19):
+
+- The sim **suppresses the software keyboard by default** (hardware
+  keyboard connected), so keyboard-layout bugs simply cannot appear.
+  `defaults write com.apple.iphonesimulator ConnectHardwareKeyboard
+  -bool false` is **blocked by the unsandboxed-Bash hook**, and `simctl
+  ui` has no equivalent — so ask Eric to hit ⌘⇧K (I/O ▸ Keyboard ▸
+  Connect Hardware Keyboard) once the sim is up.
+- iOS then shows a one-time **swipe-typing intro** covering the keyboard;
+  `xcrun simctl spawn booted defaults write
+  com.apple.keyboard.ContinuousPath DidShowContinuousPathIntroduction
+  -bool true` clears it (works sandboxed — it writes inside the sim, not
+  host prefs).
+- `automation_drive --screenshot` captures **only the GL framebuffer**,
+  so UIKit overlays (the string editor, the keyboard) are invisible in
+  it. Use `xcrun simctl io booted screenshot <path>` instead — note it
+  captures portrait-rotated for a landscape app.
+- Android counterpart: the emulator reports `keysexposed-qwerty`
+  (`adb shell am get-config`), so any code branching on "is a hardware
+  keyboard attached" always takes the hardware path there and cannot be
+  tested; Gboard's **stylus-handwriting onboarding** blocks the keyboard
+  until `adb shell settings put secure stylus_handwriting_enabled 0`.
 
 ### Simulator build/launch recipe (verified 2026-06-18)
 

docs/design/ios-tvos-app-platform.md

@@ -23,7 +23,7 @@
     "bauiv1lib": "buil"
   },
   "efrocache_repository_url": "https://files.ballistica.net/cache/ba1",
-  "engine_build_number": 22997,
+  "engine_build_number": 22998,
   "name": "BallisticaKit",
   "public": true,
   "python_paths": [
@@ -43,5 +43,5 @@
     "tests",
     "config"
   ],
-  "version": "1.8.0a100"
+  "version": "1.8.0a101"
 }

pconfig/projectconfig.json

@@ -1,7 +1,7 @@
 cpplint==2.0.2
 cryptography==50.0.0
 dmgbuild==1.6.7
-filelock==3.32.3
+filelock==3.32.4
 furo==2025.12.19
 libcst==1.9.0
 mypy==2.3.1

pconfig/requirements.txt

@@ -479,9 +479,9 @@ ds-store==1.3.3 \
     --hash=sha256:a7380896ea1e880f7ba07c5cdc24bd1530fb86836cad0be531f3e80e2d721ac5 \
     --hash=sha256:b92a371efbf1b4ccce2a04d1ed13fceacc4736c81ba09cf5aefb74c088160a35
     # via dmgbuild
-filelock==3.32.3 \
-    --hash=sha256:0ffa185a3540854c95caa7fa76b76cb219d907415e2c5dc9af25fd970563487f \
-    --hash=sha256:7f0ca4bcc0e181c60dbbd8aa9ab5b120ebb99e4e064e83636340056f833a1f09
+filelock==3.32.4 \
+    --hash=sha256:22e58ca3b1ae3b98993b762d7338367ae64fe50252bf78d59da3bfebcdf1cedd \
+    --hash=sha256:2bde2e4cf732e0153406d8a7bc80620ecf5e621fe0d25e41143c4e3b4733ff30
     # via -r pconfig/requirements.txt
 furo==2025.12.19 \
     --hash=sha256:188d1f942037d8b37cd3985b955839fea62baa1730087dc29d157677c857e2a7 \
@@ -491,9 +491,9 @@ idna==3.19 \
     --hash=sha256:5e0811a4383b21dc5838069f801c4fb62113b7447663d2530d2bd6e77b49bf15 \
     --hash=sha256:815e7be7a7806d54abb586dc943addc79e8b2ee16915059658cbeff4b1b43bf4
     # via requests
-imagesize==2.0.0 \
-    --hash=sha256:5667c5bbb57ab3f1fa4bc366f4fbc971db3d5ed011fd2715fd8001f782718d96 \
-    --hash=sha256:8e8358c4a05c304f1fccf7ff96f036e7243a189e9e42e90851993c558cfe9ee3
+imagesize==2.0.1 \
+    --hash=sha256:b2ba6a4dea487a7ebcd53248d3476aca449d30db12a2dde5e0c5ca9624fd77e5 \
+    --hash=sha256:ea0c9a0384df69ed86a943a15cde37d0360b82491b3910dc2215e202e62b5b02
     # via sphinx
 importlib-metadata==9.0.0 \
     --hash=sha256:2d21d1cc5a017bd0559e36150c21c830ab1dc304dedd1b7ea85d20f45ef3edd7 \
@@ -912,9 +912,9 @@ pbxproj==4.3.3 \
     --hash=sha256:13fc8d4d66d38627040eb66fdaee425df551321417b2943dd1bb1106a48ea521 \
     --hash=sha256:76deb4e622d0abb99d01fbeff9e5a33126cdd04cb3e82864ebf7589a5e144eec
     # via -r pconfig/requirements.txt
-platformdirs==4.11.3 \
-    --hash=sha256:5ed065d443751de711da036041a7a214122efc4a4de393b3f4137ba5576540e7 \
-    --hash=sha256:66a73d38a849810252df809a3d8bcbda8e26f6c189920e7535ad608a48dbb5ab
+platformdirs==4.11.4 \
+    --hash=sha256:e34ff91a24bcddc6d939b878bdf3f5c437c9c46fe9e212b1bf455fdf1ee57586 \
+    --hash=sha256:f3373be828247211d0febabea97e238c3dfde8a60b3c90c32756fb52cb21556d
     # via
     #   black
     #   pylint

pconfig/requirements_lock.txt

@@ -55,8 +55,8 @@
 
 # Build number and version of the ballistica binary we expect to be
 # using.
-TARGET_BALLISTICA_BUILD = 22997
-TARGET_BALLISTICA_VERSION = '1.8.0a100'
+TARGET_BALLISTICA_BUILD = 22998
+TARGET_BALLISTICA_VERSION = '1.8.0a101'
 
 
 @dataclass

src/assets/ba_data/python/baenv.py

@@ -1394,6 +1394,7 @@ def _got_score_results(self, results: dict[str, Any] | None) -> None:
                                     ).evaluate()
                                 ),
                                 suppress_warning=True,
+                                suppress_logic_thread_warning=True,
                             ),
                         )
 

src/assets/ba_data/python/bascenev1lib/activity/coopscore.py

@@ -543,7 +543,12 @@ def _refresh(self) -> None:
                 v -= via_space * 0.1
                 sscale = 0.7
                 swidth = (
-                    bui.get_string_width(via, suppress_warning=True) * sscale
+                    bui.get_string_width(
+                        via,
+                        suppress_warning=True,
+                        suppress_logic_thread_warning=True,
+                    )
+                    * sscale
                 )
                 bui.textwidget(
                     parent=self._subcontainer,

src/assets/ba_data/python/bauiv1lib/account/settings.py

@@ -278,7 +278,9 @@ def _on_query_response(self, data: dict[str, Any] | None) -> None:
                 account_name_spacing = 15
                 tscale = 0.65
                 ts_height = bui.get_string_height(
-                    trophystr, suppress_warning=True
+                    trophystr,
+                    suppress_warning=True,
+                    suppress_logic_thread_warning=True,
                 )
                 sub_width = self._width - 80
                 sub_height = (
@@ -428,7 +430,11 @@ def _on_query_response(self, data: dict[str, Any] | None) -> None:
                     ).evaluate()
                     rank_str_width = min(
                         sub_width * maxwidth_scale,
-                        bui.get_string_width(rank_str, suppress_warning=True)
+                        bui.get_string_width(
+                            rank_str,
+                            suppress_warning=True,
+                            suppress_logic_thread_warning=True,
+                        )
                         * 0.55,
                     )
 
@@ -488,7 +494,11 @@ def _on_query_response(self, data: dict[str, Any] | None) -> None:
                     rank_str = f'{season_str}:    {rank_part}'
                     rank_str_width = min(
                         sub_width * maxwidth_scale,
-                        bui.get_string_width(rank_str, suppress_warning=True)
+                        bui.get_string_width(
+                            rank_str,
+                            suppress_warning=True,
+                            suppress_logic_thread_warning=True,
+                        )
                         * 0.3,
                     )