Skip to content

Jedi Knight: the largest arrays allocated at launch (+995 KB PSRAM in every other game), sizes in Kconfig - #34

Merged
finger563 merged 3 commits into
mainfrom
perf/jk-alloc-at-start
Nov 21, 2026
Merged

finger563 merged 3 commits into
mainfrom
perf/jk-alloc-at-start

Conversation

@finger563

@finger563 finger563 commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Jedi Knight's largest arrays are allocated when it starts and freed when it quits, instead of sitting in static PSRAM while every other game runs. Every other game gets about 995 KB of PSRAM:

  • static PSRAM: 2.20 MB → 1.18 MB;

  • Jedi Knight's share: 1.34 MB → 321 KB;

  • GBA in game: 5,425 → 6,420 KB free.

  • Engine (esp-cpp/OpenJKDF2 esp32/alloc-arrays-at-start, ESP32: allocate the largest arrays per session, sizes from the build OpenJKDF2#1):

    • The AI, player, collision and surface tables plus the port's directory cache (362 KB) become one block allocated at launch.
    • The unused span rasterizer's pools (630 KB) are dropped.
    • Dreamcast-only aBounce (16 KB) is dropped.
  • components/jk/generated/globals.{c,h}: regenerated from the updated cog templates.

  • jk.cpp:

    • init() allocates the block right after the arena is created, so it's the arena's first allocation and can't fragment the level's data.
    • A failed allocation quits the cart cleanly.
    • deinit() frees it after the engine and audio tasks have stopped.
  • Kconfig ("Engine table sizes", "Material (texture) cache"):

    • JK_SITHAI_MAX_ACTORS (128);
    • JK_FS_DIR_CACHE_ENTRIES (512);
    • JK_MATERIAL_PURGE_FREE_KB (2560);
    • JK_MATERIAL_PURGE_AGE_FRAMES (900).
    • The last two are the texture cache's real knobs: it evicts materials unused for that many frames once free PSRAM drops below that.
  • overlay_image.py: the merged-strings fix from Launcher: the backdrop in 64 px tiles, smaller LVGL draw buffers (redraws 57 -> 41 ms, +184 KB in games) #30, which this change's new layout also needed. It's identical, so the two PRs merge cleanly.

Testing (Tab5)

  • A new game through the cutscenes into level 1: 9.8 MB free in the level.
  • Played, saved to a new slot and loaded it back in the same session.
  • Quit, relaunched, played GBA afterwards.
  • Two problems found while testing this were fixed in Jedi Knight: a save loaded during the intro no longer crashes; no heap fragmentation after a session #35, stacked on this PR:
    • Loading a save during JK's intro crashed. It was a NULL static world, and main does the same.
    • The PSRAM heap was fragmented after a session, by the COG lexer's and the mixer's once-per-process buffers.

Merge esp-cpp/OpenJKDF2#1 first; this PR's submodule points at its branch.

🤖 Generated with Claude Code

https://claude.ai/code/session_01SFCMzomCZ5wRHJN4sxwkvY

finger563 and others added 2 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
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
@finger563
finger563 merged commit 91fd0a0 into main Nov 21, 2026
1 check passed
@finger563
finger563 deleted the perf/jk-alloc-at-start branch November 21, 2026 04:49
finger563 added a commit that referenced this pull request Nov 21, 2026
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
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