// Adapted from MacNativeGames games/totk/runtime/game_patches.c @ ebe621d (MIT, Copyright (c) 2026 MacNativeGames // contributors): runtime_frame_step_update (2338bb0: no 1/120 s floor) and the speed survey's player chain // (world_survey.c player_actor). // Frame rate: 60 fps and the real-time frame step, the host half of the patch sets fps60, realtime and cloth // (build table patches-v121.txt; docs/research/macnativegames.md section 6.2). // // TotK's adaptive present-interval controller (main+0x8f26c8) turns the main thread's measured work into a number of // 60 Hz ticks clamped to [minimum, maximum]; shipping data sets the minimum to 2 (30 fps), the set fps60 lowers it to // 1. The controller still raises the interval when a frame does not fit. Shipping code then steps the game by whole // vsyncs (VFR step main+0x7ede6c: ratio = interval * 0.5, seconds = interval / 60; global ratio at main+0x8f2394), so // game speed is right only when frames take exactly their interval. With the set realtime both read the patch page // instead: +0 ratio = seconds * 30, +4 seconds, the moving average of the last 5 display intervals, at most 1/15 s // (slower frames slow the game down, as on the console), no lower bound, so a higher frame-rate cap only changes the // pacer (nvn_api_obj.c VSYNC_HZ). The set cloth gives hair and cloth the same clock and needs realtime. // // The sample is the display time the pacer gives each present (nvnQueuePresentTexture), so the step follows the // frames as shown, pacing waits included. With the step on, the pacer ignores the game's interval and holds a frame // only to the frame-rate cap (nvn_api_obj.c present_period): the controller's 2 or 3 vsyncs would only add latency. // One 64-bit store per present; the guest reads the two floats on its own // threads, and both stay finite and in range whichever store they see. // // TOTK_TRACE=perf adds a line per 120 presents: fps, the game seconds stepped against wall seconds, and with // TOTK_SPEED_PROBE=1 the player's position and ground speed (an independent check: Link runs at the same speed at // any frame rate when game time follows wall time). #include #include #include #include #include #include #include "cfg.h" #include "host.h" #include "layout.h" #include "platform/platform.h" #define STEP_SAMPLES 5 #define STEP_MAX_S (1.0 / 15.0) // longest step; a longer frame slows the game down #define STEP_RESET_S 0.25 // a gap this long (loading, a debugger) restarts the average #define STEP_FIRST_S (1.0 / 60.0) static _Atomic uint64_t *step_word; // patch page +0: ratio (low float), seconds (high float) static uint64_t last_ns; static double samples[STEP_SAMPLES]; static unsigned sample_count, sample_next; static uint64_t step_bits(float seconds) { float ratio = seconds * 30.0f; uint32_t lo, hi; memcpy(&lo, &ratio, 4); memcpy(&hi, &seconds, 4); return (uint64_t)lo | (uint64_t)hi << 32; } void frame_step_init(void) { int fps60 = rt_patch_set("fps60"), realtime = rt_patch_set("realtime"), cloth = rt_patch_set("cloth"); if (realtime < 0) { rt_log("frame rate: no patch table, shipping 30 fps whole-vsync steps"); return; } if (!rt_patch_enabled(realtime) && rt_patch_enabled(cloth)) { rt_patch_disable(cloth); rt_log("frame rate: cloth clock off, it needs the real-time step (TOTK_REALTIME=0)"); } if (rt_patch_enabled(realtime)) { step_word = (_Atomic uint64_t *)rt_patch_page(); atomic_store(step_word, step_bits((float)STEP_FIRST_S)); } rt_log("frame rate: present interval %s, %s", rt_patch_enabled(fps60) ? "1..3 (60 fps)" : "2..3 (shipping 30 fps)", step_word ? "real-time step (5-frame average of display intervals, at most 1/15 s)" : "whole-vsync steps"); } int frame_step_realtime(void) { return step_word != NULL; } // ---- TOTK_TRACE=perf speed lines static uint64_t win_t0, win_frames, win_hist[4]; // win_hist: frames by present interval 1, 2, 3+ ([0] unused) static double win_game; static int probe = -1; static float last_pos[3]; static uint64_t last_pos_ns; static int read_guest(uint64_t a, void *out, size_t n) { return a && plat_mem_read(a, out, n); } static uint64_t read_ptr(uint64_t a) { uint64_t p = 0; return read_guest(a, &p, 8) ? p : 0; } // 1.2.1: [main+0x4728538] +0x1e8 scene, its component 13 lists the resident actors; the one named "Player" has its // position at +0x2b4 (MacNativeGames world_survey.c, game_version.h TOTK_GAME_V121). static int player_pos(float xyz[3]) { uint64_t module = read_ptr(MOD_MAIN_BASE + 0x4728538), scene = module ? read_ptr(module + 0x1e8) : 0; int32_t count = 0; if (!scene || !read_guest(scene + 0x50, &count, 4) || count < 14 || count > 256) return 0; uint64_t comps = read_ptr(scene + 0x58), resident = comps ? read_ptr(comps + 13 * 8) : 0; if (!resident || !read_guest(resident + 0x20, &count, 4) || count < 1 || count > 64) return 0; uint64_t links = read_ptr(resident + 0x28); for (int i = 0; links && i < count; i++) { uint64_t data = read_ptr(links + (uint64_t)i * 0x70 + 8), actor = data ? read_ptr(data + 0x40) : 0; uint64_t name = actor ? read_ptr(actor + 0x218) : 0; char text[7]; if (name && read_guest(name, text, 7) && !memcmp(text, "Player", 7)) return read_guest(actor + 0x2b4, xyz, 12) && isfinite(xyz[0]) && isfinite(xyz[2]); } return 0; } static void speed_report(uint64_t now, double step, int interval) { if (!win_t0) { win_t0 = now; return; } win_frames++; win_game += step; win_hist[interval < 1 ? 1 : interval > 3 ? 3 : interval]++; if (win_frames < 120) return; if (probe < 0) { const char *e = cfg_get("TOTK_SPEED_PROBE"); probe = e && !strcmp(e, "1"); } double wall = (double)(now - win_t0) * 1e-9; char pos[160] = ""; float p[3]; if (probe && player_pos(p)) { double d = last_pos_ns ? hypot(p[0] - last_pos[0], p[2] - last_pos[2]) : 0, s = last_pos_ns ? (double)(now - last_pos_ns) * 1e-9 : 0; snprintf(pos, sizeof pos, "; player %.1f %.1f %.1f, %.2f m in %.3f s = %.2f m/s", p[0], p[1], p[2], d, s, s > 0 ? d / s : 0); memcpy(last_pos, p, sizeof p); last_pos_ns = now; } if (step_word) rt_log("fps: %llu frames in %.3f s (%.1f fps), %.3f s game stepped, speed %.3f; interval 1/2/3+ %llu/%llu/%llu%s", (unsigned long long)win_frames, wall, (double)win_frames / wall, win_game, win_game / wall, (unsigned long long)win_hist[1], (unsigned long long)win_hist[2], (unsigned long long)win_hist[3], pos); else rt_log("fps: %llu frames in %.3f s (%.1f fps), whole-vsync steps; interval 1/2/3+ %llu/%llu/%llu%s", (unsigned long long)win_frames, wall, (double)win_frames / wall, (unsigned long long)win_hist[1], (unsigned long long)win_hist[2], (unsigned long long)win_hist[3], pos); win_t0 = now; win_frames = 0; win_game = 0; memset(win_hist, 0, sizeof win_hist); } void frame_step_present(uint64_t display_ns, int interval) { double step = 0; if (step_word && last_ns) { double dt = (double)(display_ns - last_ns) * 1e-9; if (dt > STEP_RESET_S || dt < 0.001) { sample_count = sample_next = 0; } else { if (dt > STEP_MAX_S) dt = STEP_MAX_S; samples[sample_next++ % STEP_SAMPLES] = dt; if (sample_count < STEP_SAMPLES) sample_count++; double sum = 0; for (unsigned i = 0; i < sample_count; i++) sum += samples[i]; step = sum / sample_count; atomic_store_explicit(step_word, step_bits((float)step), memory_order_release); } } last_ns = display_ns; if (rt_trace & RT_TRACE_PERF) speed_report(display_ns, step, interval); }