Skip to content

Jedi Knight: a save loaded during the intro no longer crashes; no heap fragmentation after a session - #35

Merged
finger563 merged 8 commits into
mainfrom
fix/jk-fresh-load
Nov 21, 2026
Merged

finger563 merged 8 commits into
mainfrom
fix/jk-fresh-load

Conversation

@finger563

Copy link
Copy Markdown
Contributor

Stacked on #34. Engine side: esp-cpp/OpenJKDF2#2.

Summary

  • Loading a Jedi Knight save during its intro no longer crashes.
    • This happens with the pause menu, emulink load, or right after launching. main crashes too.
    • The load skipped JK's title screen, the only place that opened static.jkl, so restoring the player's animation state read through a NULL static world. The engine now opens it when the title hasn't run.
    • A load while one of JK's own menus is open now closes them and loads. Before, nothing happened until you left the menus.
  • Quitting JK at its main menu returns to the launcher. It used to hang.
  • No more heap fragmentation after a JK session.
    • The COG lexer's 16 KB buffer (made by the first level load) and the mixer's buffer stayed in the middle of the PSRAM heap for the rest of the boot. The launcher's largest free block dropped from 18.4 MB to 9.5–12.5 MB, though free memory was unchanged.
    • jk::deinit now frees both once the engine and the audio task have stopped.
    • Found with heap walks across a session: the 16,896-byte block appeared during the level load and never went away.

Testing (Tab5)

Test Before Now
Load slot 0, 1 or 2 during the intro crash (sithKeyFrame_GetByIdx) the level loads
Load after a quit and relaunch, during the intro crash the level loads
Load while JK's Players menu is open nothing happened the menus close, the level loads
Quit at JK's main menu hang back to the launcher
Largest free PSRAM block after a JK session 10.7 MB (after 3 sessions) 14.8 MB, steady across sessions
GBA after 3 JK sessions 6,419 KB free, as after a fresh boot

The remaining gap to the boot value (18.4 MB) stays the same across sessions and doesn't reduce the next game's memory. It looks like where the launcher puts its cover and console-art caches after a game.

Separately, emulink's panic report on the P4 shows a stale fault address (0x50108094): devlink.cpp fills excvaddr only for Xtensa. Not fixed here.

🤖 Generated with Claude Code

https://claude.ai/code/session_01SFCMzomCZ5wRHJN4sxwkvY

finger563 and others added 5 commits November 20, 2026 16:58
…(~1 MB less static PSRAM)

Every core's .bss is summed into static PSRAM, so Jedi Knight's 1.31 MB of
statics was reserved in every other game. The engine (OpenJKDF2 bump to
esp32/alloc-arrays-at-start) now keeps its largest arrays as pointers: jk.cpp
allocates them in one zeroed block from the engine heap right after the ROM
arena is set up, before the engine task starts (a launch without the memory
fails cleanly: the cart quits), and frees them in deinit() once the engine
and audio tasks are gone. Each launch gets fresh zeroed buffers.

- per launch (362 KB at the defaults): sithAI_actors, jkPlayer_playerInfos,
  jkPlayer_otherThings, jkPlayer_aMotsInfos, aEntryStack,
  sithCollision_aCollisions, sithSurface_aSurfaces, the port's directory
  cache
- gone: the active-edge rasterizer pools (616 KB, unused with the z-buffered
  rasterizer) and sithSound's bounce buffer (16 KB, unused on ESP32)

generated/globals.{c,h} declare the five moved globals as pointers under
PLATFORM_SESSION_ARRAYS, as the updated cog templates generate them.

Kconfig "Engine table sizes": AI actors (128), directory cache entries (512),
active-edge faces / spans (1024 / 2048, not allocated with the z-buffered
rasterizer), passed to the engine as compile definitions.

.ext_ram.bss: 2,197,512 -> 1,179,912 bytes; JK's share 1,338,411 -> 320,851.

overlay_image.py check 2c skips merged string sections (.str1.N): text holds
no addresses, and with the smaller .ext_ram.bss the overlay moved to where two
string words in esp_stdio's .rodata happened to fall (false positive).

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

Review follow-ups to the per-launch engine arrays:

- Kconfig: the "Active-edge rasterizer faces/spans" options are gone (and
  their -D lines): with RDRASTER_SW_ZBUFFER those pools are never allocated,
  so the options changed nothing. rdActive.h keeps its defaults.
- Kconfig: new "Material (texture) cache" menu. The cache has no fixed size
  (it grows into free memory and evicts on allocation failure); its two real
  knobs are now options, passed to the engine as -D values:
  JK_MATERIAL_PURGE_FREE_KB (2560: evict unused materials while less than
  this is free; 0 turns it off) and JK_MATERIAL_PURGE_AGE_FRAMES (900).
- jk.cpp (JK_ESP_DEBUG builds): the allocation dump says the session arrays
  block (jk_esp_arrays_bytes()) is among the live allocations until deinit()
  frees it, so it is not read as a leak.
- CMakeLists: the static-state comment now says ~320 KB.
- OpenJKDF2 6a5d1d96: the eviction knobs, and jkPlayer_Shutdown's MoTS loop
  frees its own polyline thing (it named jkPlayer_otherThings).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SFCMzomCZ5wRHJN4sxwkvY
Bumps components/jk/OpenJKDF2 to esp32/fix-fresh-load (0ac4f63c).

The pause-menu (or emulink) Load of a JK save shortly after launching JK
crashed the jk_engine task in sithKeyFrame_GetByIdx: the intro was still
playing, so the engine had not shown its title screen, which is where it
opens static.jkl; the load switched straight to the level and the save's
first static keyframe dereferenced a NULL static world. The engine now
opens static.jkl (and items.dat) for a level reached without the title,
reads the remembered player profile for a load before the Players dialog,
and a load issued at one of the engine's menus closes them instead of
waiting for the user to leave them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SFCMzomCZ5wRHJN4sxwkvY
…er hangs; quitting JK at its main menu returns to the launcher

Engine follow-ups to the fresh-load fix (OpenJKDF2 6aa71237):

- the pause menu's load closes the engine's menus; the Force, tally and
  first-run Players screens reopened on that and spun forever (Quit could
  not end it), and the end-of-level, dark/light choice and cutscenes
  screens replaced the load with the main menu. A load during an
  inter-level cutscene was replaced by the next level.
- static.jkl for a load from the intro is opened before the save's episode
  GOB is mounted, as the title screen does.
- quitting while JK's main menu was open never returned (deinit waited
  forever): the quit closes the menus the same way now.

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

After a Jedi Knight session the launcher's largest free PSRAM block was
9.5-12.5 MB instead of 18.4 MB (free memory unchanged): the COG lexer's
16 KB buffer, made by the first level load, and the mixer's chunk buffer
stayed in the middle of the heap for the rest of the boot (found with heap
walks across a session: the 16,896 byte block appeared during the level
load and never went away). jk::deinit now frees both once the engine and
the audio task have stopped (OpenJKDF2 esp32/fix-fresh-load).

Measured, three sessions loading saves: the largest block after each quit
14.8 MB (was 10.7 MB), free memory back to the boot value, the levels of
the second and third sessions load (the lexer is made again), GBA
afterwards has 6,419 KB free as after a fresh boot.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SFCMzomCZ5wRHJN4sxwkvY
finger563 and others added 2 commits November 20, 2026 22:27
tools/overlay_image.py: both sides added the merged-strings exception (#30
and this branch); main's version is kept.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SFCMzomCZ5wRHJN4sxwkvY
Base automatically changed from perf/jk-alloc-at-start to main November 21, 2026 04:49
The conflicts (jk.cpp, jk_esp.h, the OpenJKDF2 submodule) were #34's own
changes against their squashed copy; this branch already contains them, so
the result is this branch's tree (6a715074 contains 6a5d1d96).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SFCMzomCZ5wRHJN4sxwkvY
@finger563
finger563 merged commit 757af75 into main Nov 21, 2026
1 check passed
@finger563
finger563 deleted the fix/jk-fresh-load branch November 21, 2026 04:50
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