Scene.set() JS lifecycle, UI sprite caching, emulator test scripts

- Add Scene.set(module) so JerryScript can switch scenes via
  require()'d {init, update, dispose} modules; wire it into
  engineUpdate() and rework overworldscene.js/init.js to the new shape.
- Fix scriptManagerExecFile() never pushing its own file's directory
  onto the require() dir stack, breaking relative require() calls from
  a top-level entry script (e.g. init.js -> ./overworldscene.js).
- Cache sprite geometry across frames for uislider/uitab/uiframe
  (dialogs/textbox/settings) and give uitextbox a per-page glyph cache
  instead of one spriteBatchBuffer call per visible character. uiconsole
  drops its alloc/free vertex buffer for a fixed-size one. uifps skips
  rebuilding its label when the text hasn't changed.
- Add PSP_OPTIMIZATION_PLAN.md and a handful of UI/spritebatch unit
  tests covering the new caching logic.
- Add Dolphin/PPSSPP emulator smoke-test scripts (+ Docker variants and
  CI jobs) for GameCube/Wii/PSP.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

test/CMakeLists.txt

@@ -16,4 +16,5 @@ add_subdirectory(scene)
 # add_subdirectory(item)
 add_subdirectory(script)
 add_subdirectory(time)
+add_subdirectory(ui)
 add_subdirectory(util)

test/display/CMakeLists.txt

@@ -6,4 +6,5 @@
 include(dusktest)
 
 # Tests
-dusktest(test_color.c)
+dusktest(test_color.c)
+dusktest(test_spritebatchsprite.c)

test/display/test_spritebatchsprite.c

@@ -0,0 +1,92 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#include "dusktest.h"
+#include "display/spritebatch/spritebatchsprite.h"
+
+static void test_spriteBatchSpriteTilesetPosition_create(void **state) {
+  tileset_t tileset = {
+    .tileWidth = 8,
+    .tileHeight = 8,
+    .tileCount = 4,
+    .columns = 2,
+    .rows = 2,
+    .uv = { 0.5f, 0.5f }
+  };
+
+  spritebatchsprite_t sprite = spriteBatchSpriteTilesetPosition(
+    &tileset, 1, 1, 10.0f, 20.0f, 8.0f, 8.0f
+  );
+
+  assert_float_equal(sprite.min[0], 10.0f, 0.0001f);
+  assert_float_equal(sprite.min[1], 20.0f, 0.0001f);
+  assert_float_equal(sprite.min[2], 0.0f, 0.0001f);
+  assert_float_equal(sprite.max[0], 18.0f, 0.0001f);
+  assert_float_equal(sprite.max[1], 28.0f, 0.0001f);
+  assert_float_equal(sprite.uvMin[0], 0.5f, 0.0001f);
+  assert_float_equal(sprite.uvMin[1], 0.5f, 0.0001f);
+  assert_float_equal(sprite.uvMax[0], 1.0f, 0.0001f);
+  assert_float_equal(sprite.uvMax[1], 1.0f, 0.0001f);
+}
+
+static void test_spriteBatchSpriteTilesetPosition_zeroSize(void **state) {
+  tileset_t tileset = {
+    .tileWidth = 8,
+    .tileHeight = 8,
+    .tileCount = 1,
+    .columns = 1,
+    .rows = 1,
+    .uv = { 1.0f, 1.0f }
+  };
+
+  spritebatchsprite_t sprite = spriteBatchSpriteTilesetPosition(
+    &tileset, 0, 0, 10.0f, 20.0f, 0.0f, 8.0f
+  );
+
+  assert_float_equal(sprite.min[0], 0.0f, 0.0001f);
+  assert_float_equal(sprite.min[1], 0.0f, 0.0001f);
+  assert_float_equal(sprite.max[0], 0.0f, 0.0001f);
+  assert_float_equal(sprite.max[1], 0.0f, 0.0001f);
+}
+
+static void test_spriteBatchSpriteTranslate(void **state) {
+  spritebatchsprite_t sprite = {
+    .min = { 1.0f, 2.0f, 0.0f },
+    .max = { 5.0f, 6.0f, 0.0f },
+    .uvMin = { 0.25f, 0.5f },
+    .uvMax = { 0.75f, 1.0f }
+  };
+
+  spritebatchsprite_t translated = spriteBatchSpriteTranslate(
+    &sprite, 10.0f, -3.0f
+  );
+
+  assert_float_equal(translated.min[0], 11.0f, 0.0001f);
+  assert_float_equal(translated.min[1], -1.0f, 0.0001f);
+  assert_float_equal(translated.max[0], 15.0f, 0.0001f);
+  assert_float_equal(translated.max[1], 3.0f, 0.0001f);
+
+  // UVs must be untouched by translation.
+  assert_float_equal(translated.uvMin[0], 0.25f, 0.0001f);
+  assert_float_equal(translated.uvMin[1], 0.5f, 0.0001f);
+  assert_float_equal(translated.uvMax[0], 0.75f, 0.0001f);
+  assert_float_equal(translated.uvMax[1], 1.0f, 0.0001f);
+
+  // Original sprite must be untouched.
+  assert_float_equal(sprite.min[0], 1.0f, 0.0001f);
+  assert_float_equal(sprite.min[1], 2.0f, 0.0001f);
+}
+
+int main(int argc, char **argv) {
+  const struct CMUnitTest tests[] = {
+    cmocka_unit_test(test_spriteBatchSpriteTilesetPosition_create),
+    cmocka_unit_test(test_spriteBatchSpriteTilesetPosition_zeroSize),
+    cmocka_unit_test(test_spriteBatchSpriteTranslate),
+  };
+
+  return cmocka_run_group_tests(tests, NULL, NULL);
+}

test/script/test_overworldscene.c

@@ -17,20 +17,18 @@
 #include "display/mesh/plane.h"
 #include "display/mesh/capsule.h"
 #include "script/scriptmanager.h"
+#include "script/module/scene/modulescene.h"
 #include <math.h>
 #include <stdio.h>
+#include <string.h>
 
 #ifndef DUSK_ASSETS_DIR
   #error "DUSK_ASSETS_DIR must be defined"
 #endif
 
-// Reads the real, shipped overworldscene.js from disk (not a copy embedded
-// in this test) so this test actually verifies what ships.
-static char_t *readScriptSource(void) {
+static char_t *readFile(const char_t *relativePath) {
   char_t path[512];
-  snprintf(
-    path, sizeof(path), "%s/scripts/overworldscene.js", DUSK_ASSETS_DIR
-  );
+  snprintf(path, sizeof(path), "%s/%s", DUSK_ASSETS_DIR, relativePath);
 
   FILE *f = fopen(path, "rb");
   assert_non_null(f);
@@ -47,6 +45,26 @@ static char_t *readScriptSource(void) {
   return buf;
 }
 
+// Runs the real, shipped overworldscene.js through Scene.set() the same
+// way require()/init.js would -- not a copy embedded in this test, so
+// this actually verifies what ships.
+static errorret_t installOverworldScene(void) {
+  char_t *fileSrc = readFile("scripts/overworldscene.js");
+
+  const char_t *prefix = "var module = { exports: {} };\n(function(module){\n";
+  const char_t *suffix = "\n})(module);\nScene.set(module.exports);";
+  size_t wrappedLen = strlen(prefix) + strlen(fileSrc) + strlen(suffix);
+  char_t *wrapped = (char_t *)memoryAllocate(wrappedLen + 1);
+  snprintf(
+    wrapped, wrappedLen + 1, "%s%s%s", prefix, fileSrc, suffix
+  );
+  memoryFree(fileSrc);
+
+  errorret_t ret = scriptManagerExec(wrapped, NULL);
+  memoryFree(wrapped);
+  return ret;
+}
+
 static int overworld_setup(void **state) {
   sceneInit();
 
@@ -71,9 +89,7 @@ static int overworld_teardown(void **state) {
 }
 
 static void test_overworldscene_builds_expected_entities(void **state) {
-  char_t *src = readScriptSource();
-  errorret_t ret = scriptManagerExec(src, NULL);
-  memoryFree(src);
+  errorret_t ret = installOverworldScene();
   assert_true(errorIsOk(ret));
 
   sceneid_t sceneId = sceneGetActive();
@@ -195,9 +211,7 @@ static void test_overworldscene_builds_expected_entities(void **state) {
 }
 
 static void test_overworldscene_update_orbits_camera(void **state) {
-  char_t *src = readScriptSource();
-  errorret_t ret = scriptManagerExec(src, NULL);
-  memoryFree(src);
+  errorret_t ret = installOverworldScene();
   assert_true(errorIsOk(ret));
 
   sceneid_t sceneId = sceneGetActive();
@@ -210,7 +224,7 @@ static void test_overworldscene_update_orbits_camera(void **state) {
   // Drive one frame with a known delta and confirm the camera orbited by
   // exactly angle = delta * speed (0.1 * 0.5 = 0.05 rad).
   TIME.delta = 0.1f;
-  ret = scriptManagerCallGlobal("update");
+  ret = moduleSceneUpdateCurrent();
   assert_true(errorIsOk(ret));
 
   vec3 camPosition;
@@ -227,6 +241,66 @@ static void test_overworldscene_update_orbits_camera(void **state) {
   TIME.delta = 0.0f;
 }
 
+static void test_scene_set_switches_and_disposes(void **state) {
+  errorret_t ret = installOverworldScene();
+  assert_true(errorIsOk(ret));
+  assert_true(sceneGetActive() != SCENE_ID_INVALID);
+
+  // Install a second, trivial scene module in place of the first. This
+  // must: call the first module's dispose(), destroy its scene, then
+  // create+activate a new one and call the new module's init().
+  ret = scriptManagerExec(
+    "var switchState = { updateCount: 0, disposed: false };\n"
+    "Scene.set({\n"
+    "  init: function() { var e = new Entity(); e.add(POSITION); },\n"
+    "  update: function() { switchState.updateCount++; },\n"
+    "  dispose: function() { switchState.disposed = true; }\n"
+    "});",
+    NULL
+  );
+  assert_true(errorIsOk(ret));
+
+  sceneid_t secondSceneId = sceneGetActive();
+  assert_true(secondSceneId != SCENE_ID_INVALID);
+
+  entitymanager_t *mgr = sceneGetEntities(secondSceneId);
+  assert_true(
+    entityGetComponent(mgr, 0, COMPONENT_TYPE_POSITION) !=
+    COMPONENT_ID_INVALID
+  );
+  // The first module's plane entity (entity 1, POSITION+PHYSICS+
+  // RENDERABLE) must be gone -- proves the old scene was actually torn
+  // down, not just deactivated. (Scene IDs are a small reused pool --
+  // SCENE_COUNT_MAX slots -- so secondSceneId == firstSceneId here is
+  // expected, not a bug: sceneCreate() picks the first free slot, and
+  // destroying firstSceneId frees that exact slot right back up.)
+  assert_true(
+    entityGetComponent(mgr, 1, COMPONENT_TYPE_POSITION) ==
+    COMPONENT_ID_INVALID
+  );
+
+  ret = moduleSceneUpdateCurrent();
+  assert_true(errorIsOk(ret));
+
+  jerry_value_t result;
+  ret = scriptManagerExec("switchState.updateCount", &result);
+  assert_true(errorIsOk(ret));
+  assert_true(jerry_value_is_number(result));
+  assert_int_equal((int)jerry_value_as_number(result), 1);
+  jerry_value_free(result);
+
+  // Switching again must call the second module's dispose().
+  ret = scriptManagerExec(
+    "Scene.set({ init: function() {} });", NULL
+  );
+  assert_true(errorIsOk(ret));
+
+  ret = scriptManagerExec("switchState.disposed", &result);
+  assert_true(errorIsOk(ret));
+  assert_true(jerry_value_is_true(result));
+  jerry_value_free(result);
+}
+
 int main(void) {
   assertInit();
   const struct CMUnitTest tests[] = {
@@ -238,6 +312,10 @@ int main(void) {
       test_overworldscene_update_orbits_camera,
       overworld_setup, overworld_teardown
     ),
+    cmocka_unit_test_setup_teardown(
+      test_scene_set_switches_and_disposes,
+      overworld_setup, overworld_teardown
+    ),
   };
   return cmocka_run_group_tests(tests, NULL, NULL);
 }

test/ui/CMakeLists.txt

@@ -0,0 +1,11 @@
+# Copyright (c) 2026 Dominic Masters
+#
+# This software is released under the MIT License.
+# https://opensource.org/licenses/MIT
+
+include(dusktest)
+
+# Tests
+dusktest(test_uiframe.c)
+dusktest(test_uislider.c)
+dusktest(test_uitab.c)

test/ui/test_uiframe.c

@@ -0,0 +1,68 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#include "dusktest.h"
+#include "ui/frame/uiframe.h"
+
+static void test_uiFrameBuildSprites_layout(void **state) {
+  UI_FRAME.tileset = (tileset_t){
+    .tileWidth = 1,
+    .tileHeight = 1,
+    .tileCount = 9,
+    .columns = 3,
+    .rows = 3,
+    .uv = { 0.25f, 0.25f }
+  };
+
+  const float_t x = 100.0f;
+  const float_t y = 50.0f;
+  const float_t width = 40.0f;
+  const float_t height = 30.0f;
+  const float_t tileW = (float_t)UI_FRAME_BORDER_WIDTH;
+  const float_t tileH = (float_t)UI_FRAME_BORDER_HEIGHT;
+
+  spritebatchsprite_t sprites[9];
+  uiFrameBuildSprites(sprites, x, y, width, height);
+
+  // Top-left corner sits exactly at the rect's origin.
+  assert_float_equal(sprites[0].min[0], x, 0.0001f);
+  assert_float_equal(sprites[0].min[1], y, 0.0001f);
+  assert_float_equal(sprites[0].max[0], x + tileW, 0.0001f);
+  assert_float_equal(sprites[0].max[1], y + tileH, 0.0001f);
+  assert_float_equal(sprites[0].uvMin[0], 0.0f, 0.0001f);
+  assert_float_equal(sprites[0].uvMin[1], 0.0f, 0.0001f);
+  assert_float_equal(sprites[0].uvMax[0], 0.25f, 0.0001f);
+  assert_float_equal(sprites[0].uvMax[1], 0.25f, 0.0001f);
+
+  // Top-middle edge stretches to fill the width minus both corners.
+  assert_float_equal(sprites[1].min[0], x + tileW, 0.0001f);
+  assert_float_equal(sprites[1].max[0], x + width - tileW, 0.0001f);
+  assert_float_equal(sprites[1].max[1], y + tileH, 0.0001f);
+
+  // Center tile fills the remaining interior on both axes.
+  assert_float_equal(sprites[4].min[0], x + tileW, 0.0001f);
+  assert_float_equal(sprites[4].min[1], y + tileH, 0.0001f);
+  assert_float_equal(sprites[4].max[0], x + width - tileW, 0.0001f);
+  assert_float_equal(sprites[4].max[1], y + height - tileH, 0.0001f);
+
+  // Bottom-right corner sits exactly at the rect's far corner, sampling
+  // tileset column 2, row 2.
+  assert_float_equal(sprites[8].min[0], x + width - tileW, 0.0001f);
+  assert_float_equal(sprites[8].min[1], y + height - tileH, 0.0001f);
+  assert_float_equal(sprites[8].max[0], x + width, 0.0001f);
+  assert_float_equal(sprites[8].max[1], y + height, 0.0001f);
+  assert_float_equal(sprites[8].uvMin[0], 0.5f, 0.0001f);
+  assert_float_equal(sprites[8].uvMin[1], 0.5f, 0.0001f);
+}
+
+int main(int argc, char **argv) {
+  const struct CMUnitTest tests[] = {
+    cmocka_unit_test(test_uiFrameBuildSprites_layout),
+  };
+
+  return cmocka_run_group_tests(tests, NULL, NULL);
+}

test/ui/test_uislider.c

@@ -0,0 +1,114 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#include "dusktest.h"
+#include "ui/widget/uislider.h"
+#include "util/memory.h"
+
+// uiSliderInitFloat/InitInt require a real font (FONT_DEFAULT) to build
+// the label's glyph cache, which needs a live GL context this test binary
+// doesn't have -- see the label size caching contract for why this is
+// safe to bypass here (uiSliderRebuildGeometry only reads slider->label's
+// already-measured width/height, it never touches the font itself).
+static void sliderSetupFloat(
+  uislider_t *slider,
+  const float_t value,
+  const float_t min,
+  const float_t max,
+  const float_t step
+) {
+  memoryZero(slider, sizeof(uislider_t));
+  slider->label.width = 20;
+  slider->label.height = 10;
+  slider->type = UI_SLIDER_TYPE_FLOAT;
+  slider->min.f = min;
+  slider->max.f = max;
+  slider->step.f = step;
+  slider->value.f = value;
+}
+
+static void sliderSetupInt(
+  uislider_t *slider,
+  const int32_t value,
+  const int32_t min,
+  const int32_t max,
+  const int32_t step
+) {
+  memoryZero(slider, sizeof(uislider_t));
+  slider->label.width = 20;
+  slider->label.height = 10;
+  slider->type = UI_SLIDER_TYPE_INT;
+  slider->min.i = min;
+  slider->max.i = max;
+  slider->step.i = step;
+  slider->value.i = value;
+}
+
+static void test_uiSliderRebuildGeometry_trackPosition(void **state) {
+  uislider_t slider;
+  sliderSetupFloat(&slider, 0.0f, 0.0f, 1.0f, 0.1f);
+  uiSliderRebuildGeometry(&slider);
+
+  const float_t expectedX = (float_t)slider.label.width + UI_SLIDER_GAP;
+  const float_t expectedY =
+    ((float_t)slider.label.height - UI_SLIDER_TRACK_HEIGHT) * 0.5f;
+
+  assert_float_equal(slider.cachedTrack.min[0], expectedX, 0.0001f);
+  assert_float_equal(slider.cachedTrack.min[1], expectedY, 0.0001f);
+  assert_float_equal(
+    slider.cachedTrack.max[0], expectedX + UI_SLIDER_TRACK_WIDTH, 0.0001f
+  );
+}
+
+static void test_uiSliderRebuildGeometry_fillVisibility(void **state) {
+  uislider_t slider;
+
+  // At the minimum value, the ratio is 0 -- no fill should be visible.
+  sliderSetupFloat(&slider, 0.0f, 0.0f, 10.0f, 1.0f);
+  uiSliderRebuildGeometry(&slider);
+  assert_false(slider.cachedFillVisible);
+
+  // Halfway to max -- fill should cover half the track.
+  sliderSetupFloat(&slider, 5.0f, 0.0f, 10.0f, 1.0f);
+  uiSliderRebuildGeometry(&slider);
+  assert_true(slider.cachedFillVisible);
+  assert_float_equal(
+    slider.cachedFill.max[0] - slider.cachedFill.min[0],
+    UI_SLIDER_TRACK_WIDTH * 0.5f,
+    0.0001f
+  );
+}
+
+static void test_uiSliderRebuildGeometry_stepMarkers(void **state) {
+  uislider_t slider;
+
+  // 5 steps between 0 and 10 -- under the marker cap, so markers render.
+  sliderSetupInt(&slider, 0, 0, 10, 2);
+  uiSliderRebuildGeometry(&slider);
+  assert_int_equal(slider.cachedMarkerCount, 6);
+  assert_float_equal(
+    slider.cachedMarkers[0].min[0], slider.cachedTrack.min[0] -
+      UI_SLIDER_STEP_MARKER_WIDTH * 0.5f,
+    0.0001f
+  );
+
+  // 100 steps -- over the marker cap, so it falls back to a smooth fill
+  // with no markers.
+  sliderSetupInt(&slider, 0, 0, 100, 1);
+  uiSliderRebuildGeometry(&slider);
+  assert_int_equal(slider.cachedMarkerCount, 0);
+}
+
+int main(int argc, char **argv) {
+  const struct CMUnitTest tests[] = {
+    cmocka_unit_test(test_uiSliderRebuildGeometry_trackPosition),
+    cmocka_unit_test(test_uiSliderRebuildGeometry_fillVisibility),
+    cmocka_unit_test(test_uiSliderRebuildGeometry_stepMarkers),
+  };
+
+  return cmocka_run_group_tests(tests, NULL, NULL);
+}

test/ui/test_uitab.c

@@ -0,0 +1,36 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#include "dusktest.h"
+#include "ui/widget/uitab.h"
+#include "util/memory.h"
+
+// uiTabInit requires a real font (FONT_DEFAULT) to build the label's
+// glyph cache, which needs a live GL context this test binary doesn't
+// have. uiTabRebuildBackground only reads the label's already-measured
+// width/height, so it's safe to set those directly and exercise it here.
+static void test_uiTabRebuildBackground_matchesLabelSize(void **state) {
+  uitab_t tab;
+  memoryZero(&tab, sizeof(uitab_t));
+  tab.label.width = 42;
+  tab.label.height = 12;
+
+  uiTabRebuildBackground(&tab);
+
+  assert_float_equal(tab.cachedBackground.min[0], 0.0f, 0.0001f);
+  assert_float_equal(tab.cachedBackground.min[1], 0.0f, 0.0001f);
+  assert_float_equal(tab.cachedBackground.max[0], 42.0f, 0.0001f);
+  assert_float_equal(tab.cachedBackground.max[1], 12.0f, 0.0001f);
+}
+
+int main(int argc, char **argv) {
+  const struct CMUnitTest tests[] = {
+    cmocka_unit_test(test_uiTabRebuildBackground_matchesLabelSize),
+  };
+
+  return cmocka_run_group_tests(tests, NULL, NULL);
+}