Skip to content

ESP32: loading a save before the title screen no longer crashes; once-per-process buffers freed with the engine - #2

Merged
finger563 merged 3 commits into
esp32/alloc-arrays-at-startfrom
esp32/fix-fresh-load
Nov 21, 2026
Merged

finger563 merged 3 commits into
esp32/alloc-arrays-at-startfrom
esp32/fix-fresh-load

Conversation

@finger563

@finger563 finger563 commented Nov 21, 2026 •

Copy link
Copy Markdown

Stacked on #1 (esp32/alloc-arrays-at-start).

Loading a save before the title screen crashed

A save loaded from tab5-emu's pause menu while JK's intro was still playing crashed in sithKeyFrame_GetByIdx, from sithGamesave_Restore → RestoreFile → sithDSS_ProcessPuppetStatus. The static world, sithWorld_g_pStaticWorld, was NULL: the load switches VIDEO → UNK → GAMEPLAY and so skips jkMain_TitleShow. That function is the only one that opens static.jkl (the player's models, puppets and keyframes) and loads items.dat, so the save's first static keyframe (0x8022) was read through NULL. A relaunch behaved like a fresh boot.

  • jkMain_UnkShow now opens static.jkl and items.dat when the title hasn't run. It does this behind the title's loading screen, before the save's episode GOB is mounted, so the episode can't override static resources. jkMain_GameplayShow keeps the same check as a fallback.
  • The player profile: the load reads the remembered profile (jk_esp_save.c), or falls back to the default controls. Before the title, the Players dialog hasn't bound any controls.
  • A pause-menu load at one of JK's own menus now closes them (jkGuiRend_ESP32_bCloseMenus). Before, nothing happened until the user left the menus.
    • The Force, tally and new-player screens, the end-of-level, choice and cutscenes handlers, and inter-level cutscenes all keep the pending load instead of hanging or replacing it.
    • The flag is cleared at the switch and in jkGuiRend_Shutdown.
  • Quitting JK at its main menu (and those screens) now returns to the launcher; it used to wait forever.

Buffers made once per process are freed with the engine

The COG lexer's 16 KB input buffer, made by the first level load, and the software mixer's chunk buffer were kept for the whole process. In tab5-emu that left them in the middle of the PSRAM heap after the game, so the first JK session split the largest free block from 18.4 MB down to 9.5–12.5 MB for the rest of the boot.

  • sithCogParse_ESP32_ReleaseLexer() frees the lexer's buffer and resets yy_init. yyrestart() now makes a new buffer when there is none, as newer flex does.
  • stdSound_ESP32_Release() frees the mix buffer.
  • The port calls both after the engine and its audio task have stopped.

Testing (Tab5, with esp-cpp/tab5-emu#35)

  • Saves in slots 0, 1 and 2 load during the intro, which used to crash; so does a save made minutes earlier, after a quit and relaunch.
  • Loading while JK's Players menu is open closes it and loads the level.
  • Quitting at JK's main menu returns to the launcher.
  • Three sessions in a row: the largest free block after each quit is 14.8 MB, against 10.7 MB before. Free memory returns to the boot value, and the levels of the second and third sessions load, so the lexer is made again.

The fix was reviewed adversarially before testing. The review caught a hang on the Force and tally screens and a too-late static.jkl load in the first version, both fixed.

🤖 Generated with Claude Code

https://claude.ai/code/session_01SFCMzomCZ5wRHJN4sxwkvY

finger563 and others added 3 commits November 20, 2026 21:02
…pause-menu load closes the engine menus

A save loaded from the tab5-emu pause menu while the intro was still
playing crashed in sithKeyFrame_GetByIdx (load fault at +0x20,
lw a3,364(a4) with a4 = sithWorld_g_pStaticWorld = NULL; core dump: a4=0,
a3=0xffff7fff, a5=0x22, i.e. static keyframe 0x8022 on the first track of
the first DSS_PUPPETSTATUS). The static world (static.jkl) and the
inventory bins (items.dat) are loaded by jkMain_TitleShow, which runs
after the intro and before any menu can start a level; the pause menu's
load switches VIDEO -> UNK -> GAMEPLAY directly, so the level and the
save's messages were processed without them. Loading in a session that
already had a level (or that had shown the title) never hit this.

- jkMain_GameplayShow: if no static world is open yet, open static.jkl
  and load items.dat, as jkMain_TitleShow and Main_StartupDedicated's
  autostart do. A no-op on every path that went through the title.
- jk_esp_engine_load: before the title the Players dialog has not read a
  profile either (controls have no bindings): read the remembered player's
  profile, or fall back to the default controls.
- jk_esp_engine_load at an engine menu (main menu, Players dialog, Single
  Player, Setup, the in-game Esc menu): the level switch only happens once
  no modal menu is open, and on RETRO targets a menu does not close by
  itself for jkGuiRend_thing_four, so the load waited for the user to leave
  the menus (and New Game replaced it). jkGuiRend_ESP32_bCloseMenus makes
  every menu return -1 and jkGuiMain_Show leave its loop until
  jkMain_GuiAdvance performs the switch.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SFCMzomCZ5wRHJN4sxwkvY
… / new player screens; static.jkl before the episode GOB; quit at the main menu returns

Review follow-ups to the fresh-load fix (0ac4f63):

- jkGuiRend_ESP32_bCloseMenus made every menu return -1, but the Force
  and single-player tally screens answer -1 with an "abort?" Yes/No (which
  then also returned -1, i.e. No) and reopened, and the new player dialog
  reopens on -1 while no profile exists: a load at Esc > Jedi Powers, the
  end-of-level tally or star screen, the dark/light choice or a first-run
  Players dialog spun forever and Quit could not end it. Those screens now
  return while the flag is set (the new player dialog with the default
  controls, since no profile was read).
- jkMain_EndLevelScreenShow, jkMain_ChoiceShow and the cutscenes menu fall
  back to the main menu on -1, which replaced the pending load (the cart
  reported success): skipped while the flag is set.
- jkMain_VideoLeave starts the next level when an inter-level cutscene
  (VIDEO3 / VIDEO4) ends, and jkMain_GuiAdvance takes that state over the
  one it is switching to: a load during one was replaced by the next level.
  Skipped when switching to JK_GAMEMODE_UNK (only ever a load).
- static.jkl and items.dat for a level reached without the title are now
  opened in jkMain_UnkShow, with the title's loading screen, before
  jkMain_UnkTick mounts the save's episode GOB: jkRes searches the episode
  directory first, so in jkMain_GameplayShow the session's static world
  could pick up files from that episode. GameplayShow keeps the guard as a
  fallback.
- The flag is reset in jkGuiRend_Shutdown, so it cannot reach the next
  launch.
- A quit from outside the engine (Window_MessageLoop) also sets it: only
  cancelling the active menu left jkGuiMain_Show reopening the main menu,
  so a quit at JK's main menu never returned and jk::deinit waited forever.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SFCMzomCZ5wRHJN4sxwkvY
…h the engine

Both are made once per process: the lexer's 16 KB input buffer by the first
COG parse (during the first level load) and the software mixer's chunk
buffer by the first stdSound_Startup. In tab5-emu the engine runs in a
process that outlives it, so they stayed in the middle of the PSRAM heap
after the game: the first Jedi Knight session split the largest free block
from 18.4 MB to 9.5-12.5 MB for the rest of the boot.

- sithCogParse_ESP32_ReleaseLexer() deletes the lexer's buffer and resets
  yy_init; yyrestart() makes a new buffer when there is none, as newer
  flex does (this one passed the NULL buffer on).
- stdSound_ESP32_Release() frees the mix buffer and clears stdSound_bInitted
  so the next startup makes a new one.
The port calls both once the engine and its audio task have stopped.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SFCMzomCZ5wRHJN4sxwkvY
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant