No need for asset batching on text.c

CMakeLists.txt

@@ -76,6 +76,10 @@ else()
   set(DUSK_LIBRARY_TARGET_NAME "${DUSK_BINARY_TARGET_NAME}" CACHE INTERNAL ${DUSK_CACHE_TARGET})
 endif()
 
+if(NOT DEFINED DUSK_VERSION)
+  string(TIMESTAMP DUSK_VERSION "debug-%y%m%d%H%M%S")
+endif()
+
 # Definitions
 target_compile_definitions(${DUSK_LIBRARY_TARGET_NAME}
   PUBLIC
@@ -84,6 +88,7 @@ target_compile_definitions(${DUSK_LIBRARY_TARGET_NAME}
     DUSK_GAME_AUTHOR="${DUSK_GAME_AUTHOR}"
     DUSK_GAME_SHORT_DESCRIPTION="${DUSK_GAME_SHORT_DESCRIPTION}"
     DUSK_GAME_LONG_DESCRIPTION="${DUSK_GAME_LONG_DESCRIPTION}"
+    DUSK_VERSION="${DUSK_VERSION}"
 )
 
 # Toolchains

assets/cutscenes/MoveCubeCutscene.js

@@ -1,30 +0,0 @@
-
-function MoveCubeCutscene(params) {
-  Cutscene.call(this);
-  this.cube = params.cube;
-
-  var SPEED = 3.0;
-  var DURATION = 2.0;
-
-  this.anim = new Animation([
-    [
-      { time: 0.0, value: 0, easing: Easing.inOutQuad },
-      { time: DURATION, value: -(SPEED * DURATION), easing: Easing.inOutQuad },
-      { time: DURATION * 2, value: 0 }
-    ]
-  ]);
-
-  this.anim.onComplete = function() {
-    Cutscene.finish();
-  };
-}
-
-MoveCubeCutscene.prototype = Object.create(Cutscene.prototype);
-MoveCubeCutscene.prototype.constructor = MoveCubeCutscene;
-
-MoveCubeCutscene.prototype.update = function() {
-  this.anim.update(TIME.delta);
-  this.cube.position.position.x = this.anim.properties[0].value;
-};
-
-module = MoveCubeCutscene;

assets/entities/CubeEntity.js

@@ -1,24 +0,0 @@
-var OverworldEntity = include('entities/OverworldEntity.js');
-
-function CubeEntity() {
-  OverworldEntity.call(this);
-
-  this.add(RENDERABLE);
-
-  this.cubeMesh = Mesh.createCube();
-  this.renderable.mesh = this.cubeMesh;
-}
-
-CubeEntity.prototype = Object.create(OverworldEntity.prototype);
-CubeEntity.prototype.constructor = CubeEntity;
-
-CubeEntity.prototype.update = function() {
-  OverworldEntity.prototype.update.call(this);
-  var speed = 5.0;
-  var move = Input.axis2D(INPUT_ACTION_LEFT, INPUT_ACTION_RIGHT, INPUT_ACTION_UP, INPUT_ACTION_DOWN);
-  this.position.position.x += move.x * speed * TIME.delta;
-  this.position.position.z += move.y * speed * TIME.delta;
-  this.renderable.color = Color.rainbow();
-};
-
-module = CubeEntity;

assets/entities/OverworldEntity.js

@@ -1,21 +0,0 @@
-function OverworldEntity() {
-  Entity.call(this);
-
-  this.add(POSITION);
-}
-
-OverworldEntity.prototype = Object.create(Entity.prototype);
-OverworldEntity.prototype.constructor = OverworldEntity;
-
-OverworldEntity.prototype.update = function() {
-  // var speed = 3.0;
-  // var move = Input.axis2D(INPUT_ACTION_LEFT, INPUT_ACTION_RIGHT, INPUT_ACTION_UP, INPUT_ACTION_DOWN);
-  // this.position.position.x += move.x * speed * TIME.delta;
-  // this.position.position.z += move.y * speed * TIME.delta;
-}
-
-OverworldEntity.prototype.dispose = function() {
-  Entity.prototype.dispose.call(this);
-}
-
-module = OverworldEntity;

assets/init.js

@@ -1,93 +1,12 @@
-Console.visible = true;
+Console.print('This is called from JavaScript');
 
-// Default input bindings.
+const platformNames = {
-if (typeof PSP !== 'undefined') {
+  [System.PLATFORM_LINUX]:    'Linux',
-  Input.bind("up", INPUT_ACTION_UP);
+  [System.PLATFORM_KNULLI]:   'Knulli',
-  Input.bind("down", INPUT_ACTION_DOWN);
+  [System.PLATFORM_PSP]:      'PSP',
-  Input.bind("left", INPUT_ACTION_LEFT);
+  [System.PLATFORM_GAMECUBE]: 'GameCube',
-  Input.bind("right", INPUT_ACTION_RIGHT);
+  [System.PLATFORM_WII]:      'Wii',
-  Input.bind("accept", INPUT_ACTION_ACCEPT);
+};
-  Input.bind("cancel", INPUT_ACTION_CANCEL);
-  Input.bind("select", INPUT_ACTION_RAGEQUIT);
-  Input.bind("lstick_up", INPUT_ACTION_UP);
-  Input.bind("lstick_down", INPUT_ACTION_DOWN);
-  Input.bind("lstick_left", INPUT_ACTION_LEFT);
-  Input.bind("lstick_right", INPUT_ACTION_RIGHT);
-  Input.bind("triangle", INPUT_ACTION_CONSOLE);
 
-} else if (typeof DOLPHIN !== 'undefined') {
+const platformName = platformNames[System.platform] || 'Unknown';
-  Input.bind("up", INPUT_ACTION_UP);
+Console.print('Platform: ' + platformName);
-  Input.bind("down", INPUT_ACTION_DOWN);
-  Input.bind("left", INPUT_ACTION_LEFT);
-  Input.bind("right", INPUT_ACTION_RIGHT);
-  Input.bind("b", INPUT_ACTION_CANCEL);
-  Input.bind("a", INPUT_ACTION_ACCEPT);
-  Input.bind("z", INPUT_ACTION_CONSOLE);
-  Input.bind("lstick_up", INPUT_ACTION_UP);
-  Input.bind("lstick_down", INPUT_ACTION_DOWN);
-  Input.bind("lstick_left", INPUT_ACTION_LEFT);
-  Input.bind("lstick_right", INPUT_ACTION_RIGHT);
-
-} else if (typeof LINUX !== 'undefined') {
-  if (typeof INPUT_KEYBOARD !== 'undefined') {
-    Input.bind("w", INPUT_ACTION_UP);
-    Input.bind("s", INPUT_ACTION_DOWN);
-    Input.bind("a", INPUT_ACTION_LEFT);
-    Input.bind("d", INPUT_ACTION_RIGHT);
-
-    Input.bind("left", INPUT_ACTION_LEFT);
-    Input.bind("right", INPUT_ACTION_RIGHT);
-    Input.bind("up", INPUT_ACTION_UP);
-    Input.bind("down", INPUT_ACTION_DOWN);
-
-    Input.bind("enter", INPUT_ACTION_ACCEPT);
-    Input.bind("e", INPUT_ACTION_ACCEPT);
-
-    Input.bind("q", INPUT_ACTION_CANCEL);
-
-    Input.bind("escape", INPUT_ACTION_RAGEQUIT);
-    Input.bind("`", INPUT_ACTION_CONSOLE);
-  }
-
-  if (typeof INPUT_GAMEPAD !== 'undefined') {
-    Input.bind("gamepad_up", INPUT_ACTION_UP);
-    Input.bind("gamepad_down", INPUT_ACTION_DOWN);
-    Input.bind("gamepad_left", INPUT_ACTION_LEFT);
-    Input.bind("gamepad_right", INPUT_ACTION_RIGHT);
-
-    Input.bind("gamepad_a", INPUT_ACTION_ACCEPT);
-    Input.bind("gamepad_b", INPUT_ACTION_CANCEL);
-    Input.bind("gamepad_back", INPUT_ACTION_RAGEQUIT);
-
-    Input.bind("gamepad_lstick_up", INPUT_ACTION_UP);
-    Input.bind("gamepad_lstick_down", INPUT_ACTION_DOWN);
-    Input.bind("gamepad_lstick_left", INPUT_ACTION_LEFT);
-    Input.bind("gamepad_lstick_right", INPUT_ACTION_RIGHT);
-  }
-
-  if (typeof INPUT_POINTER !== 'undefined') {
-    Input.bind("mouse_x", INPUT_ACTION_POINTERX);
-    Input.bind("mouse_y", INPUT_ACTION_POINTERY);
-  }
-
-} else {
-  print("Unknown platform, no default input bindings set.");
-}
-
-Scene.set('scenes/cube.js');
-
-// Console.print("Testing save stuff;");
-// Console.print("Save Count: " + Save.count);
-// Console.print("Save 0 exists? " + Save.exists(0));
-// try {
-//   Save.load(0);
-//   Console.print("Successfully loaded save 0.");
-// } catch (e) {
-//   Console.print("Error loading save 0: " + e);
-//   Save.delete(0);
-// }
-// Console.print("Save 0 exists? " + Save.exists(0));
-// Console.print("Writing...");
-// Save.write(0);
-// Console.print("Save 0 exists? " + Save.exists(0));
-// Console.print("Save 0 data: " + Save.load(0));

assets/maps/test/chunks/-1_0_0.js

@@ -1,17 +0,0 @@
-var CubeEntity = include('entities/CubeEntity.js');
-
-function TestChunkN100(x, y, z) {
-  MapChunk.call(this, x, y, z);
-
-  this.cube = new CubeEntity();
-  this.cube.position.position = new Vec3(-16, 0, 0);
-}
-
-TestChunkN100.prototype = Object.create(MapChunk.prototype);
-TestChunkN100.prototype.constructor = TestChunkN100;
-
-TestChunkN100.prototype.dispose = function() {
-  this.cube.dispose();
-};
-
-module = TestChunkN100;

assets/maps/test/chunks/0_0_0.js

@@ -1,17 +0,0 @@
-var CubeEntity = include('entities/CubeEntity.js');
-
-function TestChunk000(x, y, z) {
-  MapChunk.call(this, x, y, z);
-
-  this.cube = new CubeEntity();
-  this.cube.position.position = new Vec3(0, 0, 0);
-}
-
-TestChunk000.prototype = Object.create(MapChunk.prototype);
-TestChunk000.prototype.constructor = TestChunk000;
-
-TestChunk000.prototype.dispose = function() {
-  this.cube.dispose();
-};
-
-module = TestChunk000;

assets/maps/test/chunks/0_0_1.js

@@ -1,17 +0,0 @@
-var CubeEntity = include('entities/CubeEntity.js');
-
-function TestChunk001(x, y, z) {
-  MapChunk.call(this, x, y, z);
-
-  this.cube = new CubeEntity();
-  this.cube.position.position = new Vec3(0, 0, 16);
-}
-
-TestChunk001.prototype = Object.create(MapChunk.prototype);
-TestChunk001.prototype.constructor = TestChunk001;
-
-TestChunk001.prototype.dispose = function() {
-  this.cube.dispose();
-};
-
-module = TestChunk001;

assets/maps/test/chunks/0_1_0.js

@@ -1,17 +0,0 @@
-var CubeEntity = include('entities/CubeEntity.js');
-
-function TestChunk010(x, y, z) {
-  MapChunk.call(this, x, y, z);
-
-  this.cube = new CubeEntity();
-  this.cube.position.position = new Vec3(0, 16, 0);
-}
-
-TestChunk010.prototype = Object.create(MapChunk.prototype);
-TestChunk010.prototype.constructor = TestChunk010;
-
-TestChunk010.prototype.dispose = function() {
-  this.cube.dispose();
-};
-
-module = TestChunk010;

assets/maps/test/chunks/1_0_0.js

@@ -1,17 +0,0 @@
-var CubeEntity = include('entities/CubeEntity.js');
-
-function TestChunk100(x, y, z) {
-  MapChunk.call(this, x, y, z);
-
-  this.cube = new CubeEntity();
-  this.cube.position.position = new Vec3(16, 0, 0);
-}
-
-TestChunk100.prototype = Object.create(MapChunk.prototype);
-TestChunk100.prototype.constructor = TestChunk100;
-
-TestChunk100.prototype.dispose = function() {
-  this.cube.dispose();
-};
-
-module = TestChunk100;

assets/maps/test/chunks/2_0_0.js

@@ -1,17 +0,0 @@
-var CubeEntity = include('entities/CubeEntity.js');
-
-function TestChunk200(x, y, z) {
-  MapChunk.call(this, x, y, z);
-
-  this.cube = new CubeEntity();
-  this.cube.position.position = new Vec3(32, 0, 0);
-}
-
-TestChunk200.prototype = Object.create(MapChunk.prototype);
-TestChunk200.prototype.constructor = TestChunk200;
-
-TestChunk200.prototype.dispose = function() {
-  this.cube.dispose();
-};
-
-module = TestChunk200;

assets/maps/test/chunks/3_0_0.js

@@ -1,17 +0,0 @@
-var CubeEntity = include('entities/CubeEntity.js');
-
-function TestChunk300(x, y, z) {
-  MapChunk.call(this, x, y, z);
-
-  this.cube = new CubeEntity();
-  this.cube.position.position = new Vec3(48, 0, 0);
-}
-
-TestChunk300.prototype = Object.create(MapChunk.prototype);
-TestChunk300.prototype.constructor = TestChunk300;
-
-TestChunk300.prototype.dispose = function() {
-  this.cube.dispose();
-};
-
-module = TestChunk300;

assets/maps/test/init.js

@@ -1,17 +0,0 @@
-function TestMap() {
-  Map.call(this);
-
-  Map.setChunkSize(16, 16, 16);
-  Map.setPosition(0, 0, 0);
-}
-
-TestMap.prototype = Object.create(Map.prototype);
-TestMap.prototype.constructor = TestMap;
-
-TestMap.prototype.update = function() {
-};
-
-TestMap.prototype.dispose = function() {
-};
-
-module = TestMap;

assets/scenes/cube.js

@@ -1,33 +0,0 @@
-var CubeEntity = include('entities/CubeEntity.js');
-
-function CubeScene() {
-  Map.load('test');
-
-  this.cam = new Entity();
-  this.cam.add(POSITION);
-  this.cam.add(CAMERA);
-
-  this.player = new CubeEntity();
-  this.player.position.position = new Vec3(0, 0, 0);
-}
-
-CubeScene.prototype = Object.create(Scene.prototype);
-CubeScene.prototype.constructor = CubeScene;
-
-CubeScene.prototype.update = function() {
-  this.player.update();
-
-  var pos = this.player.position.position;
-  this.cam.position.position = new Vec3(pos.x, pos.y + 8, pos.z + 8);
-  this.cam.position.lookAt(pos);
-
-  Map.setPosition(Math.floor(pos.x), Math.floor(pos.y), Math.floor(pos.z));
-};
-
-CubeScene.prototype.dispose = function() {
-  this.cam.dispose();
-  this.player.dispose();
-  Map.dispose();
-};
-
-module = CubeScene;

cmake/modules/Findjerryscript.cmake

@@ -0,0 +1,96 @@
+# Copyright (c) 2026 Dominic Masters
+#
+# This software is released under the MIT License.
+# https://opensource.org/licenses/MIT
+
+# Turn things off we don't need
+set(JERRY_CMDLINE OFF CACHE BOOL "" FORCE)
+set(JERRY_EXT ON CACHE BOOL "" FORCE)
+set(JERRY_DEBUGGER OFF CACHE BOOL "" FORCE)
+set(JERRY_BUILTIN_DATE OFF CACHE BOOL "" FORCE)
+set(ENABLE_LTO OFF CACHE BOOL "" FORCE)
+
+# Fetch Jerry
+include(FetchContent)
+FetchContent_Declare(
+  jerryscript
+  GIT_REPOSITORY https://git.wish.moe/YourWishes/jerryscript
+  GIT_TAG float32-fix
+)
+FetchContent_MakeAvailable(jerryscript)
+
+# Mark found
+set(jerryscript_FOUND ON)
+
+# Define targets
+if(TARGET jerryscript-core)
+  set(JERRY_CORE_TARGET jerryscript-core)
+elseif(TARGET jerry-core)
+  set(JERRY_CORE_TARGET jerry-core)
+endif()
+
+if(TARGET jerryscript-ext)
+  set(JERRY_EXT_TARGET jerryscript-ext)
+elseif(TARGET jerry-ext)
+  set(JERRY_EXT_TARGET jerry-ext)
+endif()
+
+if(TARGET jerryscript-port-default)
+  set(JERRY_PORT_TARGET jerryscript-port-default)
+elseif(TARGET jerry-port-default)
+  set(JERRY_PORT_TARGET jerry-port-default)
+elseif(TARGET jerryscript-port)
+  set(JERRY_PORT_TARGET jerryscript-port)
+elseif(TARGET jerry-port)
+  set(JERRY_PORT_TARGET jerry-port)
+endif()
+
+if(NOT JERRY_CORE_TARGET)
+  message(FATAL_ERROR "JerryScript core target not found")
+endif()
+
+if(NOT JERRY_EXT_TARGET)
+  message(FATAL_ERROR "JerryScript ext target not found")
+endif()
+
+if(NOT JERRY_PORT_TARGET)
+  message(FATAL_ERROR "JerryScript port target not found")
+endif()
+
+foreach(tgt IN ITEMS
+  ${JERRY_CORE_TARGET}
+  ${JERRY_EXT_TARGET}
+  ${JERRY_PORT_TARGET}
+)
+  if(TARGET ${tgt})
+    set_property(TARGET ${tgt} PROPERTY INTERPROCEDURAL_OPTIMIZATION OFF)
+    target_compile_definitions(${JERRY_CORE_TARGET} PRIVATE
+      JERRY_NUMBER_TYPE_FLOAT64=0
+      JERRY_BUILTIN_DATE=0
+    )
+  endif()
+endforeach()
+
+# Export include dirs through the targets
+target_include_directories(${JERRY_CORE_TARGET} INTERFACE
+  ${jerryscript_SOURCE_DIR}/jerry-core/include
+)
+
+target_include_directories(${JERRY_EXT_TARGET} INTERFACE
+  ${jerryscript_SOURCE_DIR}/jerry-ext/include
+)
+
+target_include_directories(${JERRY_PORT_TARGET} INTERFACE
+  ${jerryscript_SOURCE_DIR}/jerry-port/default/include
+)
+
+# Suppress JerryScript-only warning
+if(CMAKE_C_COMPILER_ID MATCHES "GNU|Clang")
+  target_compile_options(${JERRY_CORE_TARGET} PRIVATE
+    -Wno-error
+  )
+endif()
+
+add_library(jerryscript::core ALIAS ${JERRY_CORE_TARGET})
+add_library(jerryscript::ext ALIAS ${JERRY_EXT_TARGET})
+add_library(jerryscript::port ALIAS ${JERRY_PORT_TARGET})

cmake/targets/knulli.cmake

@@ -34,6 +34,7 @@ target_compile_definitions(${DUSK_LIBRARY_TARGET_NAME} PUBLIC
   DUSK_OPENGL
   DUSK_OPENGL_ES
   DUSK_LINUX
+  DUSK_KNULLI
   DUSK_DISPLAY_SIZE_DYNAMIC
   DUSK_DISPLAY_WIDTH_DEFAULT=640
   DUSK_DISPLAY_HEIGHT_DEFAULT=480

cmake/targets/linux.cmake

@@ -26,6 +26,8 @@ target_link_libraries(${DUSK_LIBRARY_TARGET_NAME} PUBLIC
   # CURL::libcurl
 )
 
+set(DUSK_BACKTRACE ON CACHE BOOL "Enable backtrace support for assert failures.")
+
 # Define platform-specific macros.
 target_compile_definitions(${DUSK_LIBRARY_TARGET_NAME} PUBLIC
   DUSK_SDL2

scripts/test-linux.sh

@@ -1,4 +1,6 @@
 #!/bin/bash
+set -e
+rm -rf build-tests
 cmake -S . -B build-tests -DDUSK_BUILD_TESTS=ON -DDUSK_TARGET_SYSTEM=linux
 cmake --build build-tests -- -j$(nproc)
 ctest --output-on-failure --test-dir build-tests

src/dusk/CMakeLists.txt

@@ -32,6 +32,22 @@ if(NOT yyjson_FOUND)
   endif()
 endif()
 
+if(NOT jerryscript_FOUND)
+  find_package(jerryscript REQUIRED)
+  target_link_libraries(${DUSK_LIBRARY_TARGET_NAME} PUBLIC
+    jerryscript::core
+    jerryscript::ext
+    jerryscript::port
+  )
+endif()
+
+if(DUSK_BACKTRACE)
+  target_link_options(${DUSK_LIBRARY_TARGET_NAME} PUBLIC -rdynamic)
+  target_compile_definitions(${DUSK_BINARY_TARGET_NAME} PUBLIC
+    DUSK_BACKTRACE
+  )
+endif()
+
 # Includes
 target_include_directories(${DUSK_LIBRARY_TARGET_NAME}
   PUBLIC
@@ -62,6 +78,7 @@ add_subdirectory(input)
 add_subdirectory(locale)
 add_subdirectory(physics)
 add_subdirectory(scene)
+add_subdirectory(script)
 add_subdirectory(system)
 add_subdirectory(time)
 add_subdirectory(ui)

src/dusk/animation/CMakeLists.txt

@@ -7,5 +7,4 @@ target_sources(${DUSK_LIBRARY_TARGET_NAME}
   PUBLIC
     easing.c
     animation.c
-    animationproperty.c
 )

src/dusk/animation/animation.c

@@ -8,86 +8,45 @@
 #include "util/memory.h"
 #include "util/math.h"
 
-void animationInit(animation_t *anim) {
+void animationInit(
-  memoryZero(anim, sizeof(animation_t));
+  animation_t *anim,
-  eventInit(&anim->onStart);
+  keyframe_t *keyframes,
-  eventInit(&anim->onComplete);
+  uint16_t keyframeCount
+) {
+  assertNotNull(anim, "Animation pointer cannot be null.");
+  assertNotNull(keyframes, "Keyframes pointer cannot be null.");
+  assertTrue(keyframeCount > 0, "Keyframe count must be more than 0.");
+
+  anim->keyframes = keyframes;
+  anim->keyframeCount = keyframeCount;
 }
 
-animationproperty_t *animationAddProperty(animation_t *anim, float_t *target) {
+float_t animationGetValue(animation_t *anim, const float_t time) {
-  assertTrue(
+  assertNotNull(anim, "Animation pointer cannot be null.");
-    anim->propertyCount < ANIMATION_PROPERTY_COUNT_MAX,
+  assertNotNull(anim->keyframes, "Keyframes pointer cannot be null.");
-    "Property count exceeds ANIMATION_PROPERTY_COUNT_MAX"
+  assertTrue(anim->keyframeCount > 0, "Keyframe count invalid.");
-  );
+  assertTrue(time >= 0, "Time must be non-negative.");
-  animationproperty_t *prop = &anim->properties[anim->propertyCount++];
-  prop->keyframeCount = 0;
-  prop->target = target;
-  return prop;
-}
   
-void animationUpdate(animation_t *anim, float_t delta) {
+  keyframe_t *start;
-  assertNotNull(anim, "Animation cannot be null");
+  keyframe_t *end;
+  keyframe_t *last = anim->keyframes + anim->keyframeCount - 1;
+  keyframe_t *current = anim->keyframes;
+  start = current;
 
-  if(
+  do {
-    (anim->flags & ANIMATION_FLAG_FINISHED) &&
+    if(current->time > time) {
-    !(anim->flags & ANIMATION_FLAG_LOOP_ENABLED)
+      end = current;
-  ) return;
+      break;
-
-  bool_t wasStarted = (anim->flags & ANIMATION_FLAG_STARTED) != 0;
-  anim->flags |= ANIMATION_FLAG_STARTED;
-  anim->time += delta;
-
-  float_t duration = animationGetDuration(anim);
-  bool_t justFinished = false;
-  if(anim->time >= duration) {
-    if(anim->flags & ANIMATION_FLAG_LOOP_ENABLED) {
-      anim->time = mathModFloat(anim->time, duration);
-    } else {
-      anim->time = duration;
-      if(!(anim->flags & ANIMATION_FLAG_FINISHED)) {
-        anim->flags |= ANIMATION_FLAG_FINISHED;
-        justFinished = true;
-      }
     }
-  }
+    start = current;
+    current++;
 
-  for(uint8_t i = 0; i < anim->propertyCount; i++) {
+    if(current > last) {
-    animationproperty_t *prop = &anim->properties[i];
+      end = start;
-    if(prop->target != NULL) {
+      break;
-      *prop->target = animationPropertyGetValue(prop, anim->time);
     }
-  }
+  } while(true);
 
-  if(!wasStarted) eventInvoke(&anim->onStart, anim);
+  float_t t = (time - start->time) / (end->time - start->time);
-  if(justFinished) eventInvoke(&anim->onComplete, anim);
+  return mathLerp(start->value, end->value, easingApply(start->easing, t));
-}
-
-
-void animationReset(animation_t *anim) {
-  anim->time = 0.0f;
-  anim->flags &= ~(ANIMATION_FLAG_FINISHED | ANIMATION_FLAG_STARTED);
-}
-
-bool_t animationIsFinished(const animation_t *anim) {
-  return (anim->flags & ANIMATION_FLAG_FINISHED) != 0;
-}
-
-bool_t animationIsStarted(const animation_t *anim) {
-  return (anim->flags & ANIMATION_FLAG_STARTED) != 0;
-}
-
-bool_t animationIsLooping(const animation_t *anim) {
-  return (anim->flags & ANIMATION_FLAG_LOOP_ENABLED) != 0;
-}
-
-float_t animationGetDuration(const animation_t *anim) {
-  float_t duration = 0.0f;
-  for(uint8_t i = 0; i < anim->propertyCount; i++) {
-    animationproperty_t *prop = &anim->properties[i];
-    if(prop->keyframeCount == 0) continue;
-    float_t lastKeyframeTime =
-      prop->keyframes[prop->keyframeCount - 1].time;
-    if(lastKeyframeTime > duration) duration = lastKeyframeTime;
-  }
-  return duration;
 }

src/dusk/animation/animation.h

@@ -4,87 +4,31 @@
 // https://opensource.org/licenses/MIT
 
 #pragma once
-#include "animationproperty.h"
+#include "keyframe.h"
-#include "event/event.h"
-
-#define ANIMATION_PROPERTY_COUNT_MAX 8
-
-#define ANIMATION_FLAG_FINISHED (1 << 0)
-#define ANIMATION_FLAG_STARTED (1 << 1)
-#define ANIMATION_FLAG_LOOP_ENABLED (1 << 2)
 
 typedef struct {
-  animationproperty_t properties[ANIMATION_PROPERTY_COUNT_MAX];
+  keyframe_t *keyframes;
-  uint8_t propertyCount;
+  uint16_t keyframeCount;
-  float_t time;
-  uint8_t flags;
-  event_t onStart;
-  event_t onComplete;
 } animation_t;
 
 /**
  * Initializes an animation.
  * 
  * @param anim The animation to initialize.
+ * @param keyframes The keyframes to use for the animation.
+ * @param keyframeCount The number of keyframes in the animation.
  */
-void animationInit(animation_t *anim);
+void animationInit(
+  animation_t *anim,
+  keyframe_t *keyframes,
+  uint16_t keyframeCount
+);
 
 /**
- * Adds a new animated property. The caller owns target and must keep it valid
+ * Gets the value of the animation at a given time.
- * for the lifetime of the animation.
  * 
- * @param anim The animation to add the property to.
+ * @param anim The animation to get the value from.
- * @param target Pointer to the float to write interpolated values into.
+ * @param time The time at which to get the value, in seconds.
- * @return A pointer to the new property.
+ * @return The value of the animation at the given time.
  */
-animationproperty_t *animationAddProperty(animation_t *anim, float_t *target);
+float_t animationGetValue(animation_t *anim, const float_t time);
-
-/**
- * Advances the animation by delta seconds and writes interpolated values to
- * each property's target pointer.
- * 
- * @param anim The animation to update.
- * @param delta The time to advance the animation by, in seconds.
- */
-void animationUpdate(animation_t *anim, float_t delta);
-
-/**
- * Resets the animation to the beginning, clearing Started and Finished flags.
- * 
- * @param anim The animation to reset.
- */
-void animationReset(animation_t *anim);
-
-/**
- * Returns true if the animation has finished (i.e. reached the end of its
- * duration and is not looping).
- * 
- * @param anim The animation to check.
- * @return true if the animation has finished, false otherwise.
- */
-bool_t animationIsFinished(const animation_t *anim);
-
-/**
- * Returns true if the animation has been started (i.e. animationUpdate has
- * been called at least once).
- * 
- * @param anim The animation to check.
- * @return true if the animation has been started, false otherwise.
- */
-bool_t animationIsStarted(const animation_t *anim);
-
-/**
- * Returns true if the animation is set to loop.
- * 
- * @param anim The animation to check.
- * @return true if the animation is set to loop, false otherwise.
- */
-bool_t animationIsLooping(const animation_t *anim);
-
-/**
- * Gets the total duration of the animation (based on the keyframes).
- * 
- * @param anim The animation to get the duration of.
- * @return The total duration of the animation, in seconds.
- */
-float_t animationGetDuration(const animation_t *anim);

src/dusk/animation/animationproperty.c

@@ -1,55 +0,0 @@
-/**
- * Copyright (c) 2026 Dominic Masters
- * 
- * This software is released under the MIT License.
- * https://opensource.org/licenses/MIT
- */
-
-#include "animationproperty.h"
-#include "assert/assert.h"
-
-void animationPropertyAddKeyframe(
-  animationproperty_t *prop,
-  const float_t time,
-  const float_t value,
-  const easingtype_t easing
-) {
-  assertNotNull(prop, "Property cannot be null");
-  assertTrue(
-    prop->keyframeCount < ANIMATION_PROPERTY_KEYFRAME_COUNT_MAX,
-    "Too many keyframes added to property"
-  );
-  assertTrue(time >= 0.0f, "Keyframe time cannot be negative");
-
-  keyframe_t *frame = &prop->keyframes[prop->keyframeCount++];
-  frame->time = time;
-  frame->value = value;
-  frame->easing = easing;
-}
-
-float_t animationPropertyGetValue(
-  const animationproperty_t *prop,
-  const float_t time
-) {
-  assertNotNull(prop, "Property cannot be null");
-  assertTrue(time >= 0.0f, "Time cannot be negative");
-
-  if(prop->keyframeCount == 0) return 0.0f;
-
-  uint8_t last = prop->keyframeCount - 1;
-
-  if(prop->keyframeCount == 1) return prop->keyframes[0].value;
-  if(time <= prop->keyframes[0].time) return prop->keyframes[0].value;
-  if(time >= prop->keyframes[last].time) return prop->keyframes[last].value;
-
-  for(uint8_t i = 0; i < last; i++) {
-    const keyframe_t *a = &prop->keyframes[i];
-    const keyframe_t *b = &prop->keyframes[i + 1];
-    if(time < a->time || time >= b->time) continue;
-    float_t t = (time - a->time) / (b->time - a->time);
-    t = easingApply(a->easing, t);
-    return a->value + (b->value - a->value) * t;
-  }
-
-  return prop->keyframes[last].value;
-}

src/dusk/animation/animationproperty.h

@@ -1,45 +0,0 @@
-/**
- * Copyright (c) 2026 Dominic Masters
- * 
- * This software is released under the MIT License.
- * https://opensource.org/licenses/MIT
- */
-
-#pragma once
-#include "keyframe.h"
-
-#define ANIMATION_PROPERTY_KEYFRAME_COUNT_MAX 16
-
-typedef struct {
-  keyframe_t keyframes[ANIMATION_PROPERTY_KEYFRAME_COUNT_MAX];
-  uint8_t keyframeCount;
-  float_t *target;
-} animationproperty_t;
-
-/**
- * Appends a keyframe to a property. Keyframes must be added in ascending time
- * order. Updates the animation's duration.
- * 
- * @param property The property to add the keyframe to.
- * @param time The time of the keyframe, in seconds.
- * @param value The value of the keyframe.
- * @param easing The easing type to use when interpolating to the next keyframe.
- */
-void animationPropertyAddKeyframe(
-  animationproperty_t *property,
-  const float_t time,
-  const float_t value,
-  const easingtype_t easing
-);
-
-/**
- * Gets the property's value at a given time.
- * 
- * @param prop The property to get the value from.
- * @param time The time at which to get the value, in seconds.
- * @return The value of the property at the given time.
- */
-float_t animationPropertyGetValue(
-  const animationproperty_t *prop,
-  const float_t time
-);

src/dusk/assert/assert.c

@@ -8,6 +8,7 @@
 #include "assert.h"
 #include "log/log.h"
 #include "util/string.h"
+#include "util/memory.h"
 
 #ifndef DUSK_ASSERTIONS_FAKED
   #ifdef DUSK_TEST_ASSERT
@@ -25,6 +26,25 @@
       );
     }
   #else
+    #ifdef DUSK_BACKTRACE
+      #include <execinfo.h>
+      #include <stdlib.h>
+
+      static void assertLogBacktrace(void) {
+        void *frames[64];
+        int count = backtrace(frames, 64);
+        char **symbols = backtrace_symbols(frames, count);
+        memoryTrack(symbols);
+        logError("Stack trace:\n");
+        if(symbols) {
+          for(int i = 0; i < count; i++) {
+            logError("  %s\n", symbols[i]);
+          }
+          memoryFree(symbols);
+        }
+      }
+    #endif
+
     void assertTrueImpl(
       const char *file,
       const int32_t line,
@@ -33,11 +53,14 @@
     ) {
       if(x != true) {
         logError(
-          "Assertion Failed in %s:%i\n\n%s\n",
+          "Assertion Failed in %s:%i\n\n%s\n\n",
           file,
           line,
           message
         );
+        #ifdef DUSK_BACKTRACE
+          assertLogBacktrace();
+        #endif
         abort();
       }
     }

src/dusk/asset/CMakeLists.txt

@@ -7,6 +7,7 @@
 target_sources(${DUSK_LIBRARY_TARGET_NAME}
   PUBLIC
     asset.c
+    assetbatch.c
     assetfile.c
 )
 

src/dusk/asset/asset.c

@@ -11,15 +11,23 @@
 #include "assert/assert.h"
 #include "engine/engine.h"
 #include "util/string.h"
+#include "console/console.h"
+#include <unistd.h>
 
 asset_t ASSET;
 
 errorret_t assetInit(void) {
   memoryZero(&ASSET, sizeof(asset_t));
 
+  for(size_t i = 0; i < ASSET_LOADING_COUNT_MAX; i++) {
+    threadMutexInit(&ASSET.loading[i].mutex);
+  }
+
   // assetInitPlatform must either define ASSET.zip or throw an error.
   errorChain(assetInitPlatform());
   assertNotNull(ASSET.zip, "Asset zip null without error.");
+  threadInit(&ASSET.loadThread, assetUpdateAsync);
+  threadStart(&ASSET.loadThread);
 
   errorOk();
 }
@@ -32,24 +40,304 @@ bool_t assetFileExists(const char_t *filename) {
   return true;
 }
 
-errorret_t assetLoad(
+assetentry_t * assetGetEntry(
-  const char_t *filename,
+  const char_t *name,
-  assetfileloader_t loader,
+  const assetloadertype_t type,
-  void *params,
+  assetloaderinput_t *input
-  void *output
 ) {
-  assertStrLenMax(filename, ASSET_FILE_NAME_MAX, "Filename too long.");
+  // Is there an existing asset?
-  assertNotNull(output, "Output pointer cannot be NULL.");
+  assetentry_t *entry = ASSET.entries;
-  assertNotNull(loader, "Asset file loader cannot be NULL.");
+  do {
+    if(entry->type == ASSET_LOADER_TYPE_NULL) {
+      entry++;
+      continue;
+    }
+    if(stringEquals(entry->name, name)) {
+      assertTrue(entry->type == type, "Asset entry type mismatch.");
+      return entry;
+    }
+    entry++;
+  } while(entry < ASSET.entries + ASSET_ENTRY_COUNT_MAX);
+  
+  // We did not find one existing, Find first available slot.
+  entry = ASSET.entries;
+  do {
+    if(entry->type != ASSET_LOADER_TYPE_NULL) {
+      entry++;
+      continue;
+    }
+
+    if(entry->state == ASSET_ENTRY_STATE_NOT_STARTED) {
+      assetEntryInit(entry, name, type, input);
+      return entry;
+    }
+    entry++;
+  } while(entry < ASSET.entries + ASSET_ENTRY_COUNT_MAX);
+
+  assertUnreachable("No available asset entry slots.");
+  return NULL;
+}
+
+errorret_t assetRequireLoaded(assetentry_t *entry) {
+  assertNotNull(entry, "Entry cannot be NULL.");
+  assertTrue(entry->type != ASSET_LOADER_TYPE_NULL, "Invalid loader type.");
+
+  // Already loaded?
+  if(entry->state == ASSET_ENTRY_STATE_LOADED) {
+    errorOk();
+  }
+
+  // Not loaded, just spin the wheel
+  while(entry->state != ASSET_ENTRY_STATE_LOADED) {
+    usleep(1000);
+    errorChain(assetUpdate());
+  }
 
-  assetfile_t file;
-  errorChain(assetFileInit(&file, filename, params, output));
-  errorChain(loader(&file));
-  errorChain(assetFileDispose(&file));
   errorOk();
 }
 
+assetentry_t * assetLock(
+  const char_t *name,
+  const assetloadertype_t type,
+  assetloaderinput_t *input
+) {
+  assetentry_t *entry = assetGetEntry(name, type, input);
+  assetEntryLock(entry);
+  return entry;
+}
+
+void assetUnlock(const char_t *name) {
+  assertNotNull(name, "Name cannot be NULL.");
+  assetentry_t *entry = ASSET.entries;
+  do {
+    if(entry->type != ASSET_LOADER_TYPE_NULL && stringEquals(entry->name, name)) {
+      assetEntryUnlock(entry);
+      return;
+    }
+    entry++;
+  } while(entry < ASSET.entries + ASSET_ENTRY_COUNT_MAX);
+  assertUnreachable("Asset entry not found for unlock.");
+}
+
+void assetUnlockEntry(assetentry_t *entry) {
+  assertNotNull(entry, "Entry cannot be NULL.");
+  assetEntryUnlock(entry);
+}
+
+errorret_t assetUpdate(void) {
+  // Determine how many available loading slots we have.
+  assetloading_t *availableLoading[ASSET_LOADING_COUNT_MAX];
+  uint8_t availableLoadingCount = 0;
+  assetloading_t *loading = ASSET.loading;
+  assetentry_t *entry;
+
+
+  do {
+    // We only care about NULL entry references. Nothing async touches this so
+    // it's fine to use raw here.
+    if(loading->entry != NULL) {
+      loading++;
+      continue;
+    }
+    availableLoading[availableLoadingCount++] = loading;
+    loading++;
+  } while(loading < ASSET.loading + ASSET_LOADING_COUNT_MAX);
+
+
+  // Now we can check for pending asset entries, we can't do anything if there
+  // is no available slots though.
+  if(availableLoadingCount > 0) {
+    entry = ASSET.entries;
+    do {
+      // Is this asset "ready to start loading" ?
+      if(entry->type == ASSET_LOADER_TYPE_NULL) {
+        entry++;
+        continue;
+      }
+
+      // We only care about assets not started.
+      if(entry->state != ASSET_ENTRY_STATE_NOT_STARTED) {
+        entry++;
+        continue;
+      }
+
+      // Pop a loading slot for this asset entry.
+      loading = availableLoading[--availableLoadingCount];
+
+      // Start loading this asset.
+      assetEntryStartLoading(entry, loading);
+      entry++;
+
+      // Did we run out of loading slots?
+      if(availableLoadingCount == 0) {
+        break;
+      }
+    } while(entry < ASSET.entries + ASSET_ENTRY_COUNT_MAX);
+  }
+
+  // Now walk over all the loading slots and see what needs to be done.
+  loading = ASSET.loading;
+  do {
+    // Is the loading slot in use? Entry can only be modified synchronously.
+    if(loading->entry == NULL) {
+      loading++;
+      continue;
+    }
+
+    // Lock the loading slot. This will prevent any async modifications.
+    threadMutexLock(&loading->mutex);
+
+    // Check the state of the entry.
+    switch(loading->entry->state) {
+      // This thing is pending synchronous loading.
+      case ASSET_ENTRY_STATE_PENDING_SYNC:
+        // Perform sync load.
+        loading->entry->state = ASSET_ENTRY_STATE_LOADING_SYNC;
+        errorret_t ret = (
+          ASSET_LOADER_CALLBACKS[loading->type].loadSync(loading)
+        );
+
+        // After a sync load, these are the only valid states.
+        assertTrue(
+          loading->entry->state == ASSET_ENTRY_STATE_LOADED ||
+          loading->entry->state == ASSET_ENTRY_STATE_ERROR ||
+          loading->entry->state == ASSET_ENTRY_STATE_PENDING_SYNC ||
+          loading->entry->state == ASSET_ENTRY_STATE_PENDING_ASYNC,
+          "Loader did not set entry state to loaded or error on finished load."
+        );
+
+        // If an error occured these things need to be true, basically just
+        // ensuring the sync loader is setting the error correctly.
+        if(errorIsNotOk(ret)) {
+          errorCatch(errorPrint(ret));
+          assertTrue(
+            loading->entry->state == ASSET_ENTRY_STATE_ERROR,
+            "Loader did not set entry state to error on failed load."
+          );
+        }
+
+        threadMutexUnlock(&loading->mutex);
+        loading++;
+        break;
+
+      case ASSET_ENTRY_STATE_LOADING_SYNC:
+        assertUnreachable(
+          "Entry is in a pending sync state still?"
+        );
+        break;
+
+      // Done loading, we can just free it up.
+      case ASSET_ENTRY_STATE_LOADED:
+        loading->entry = NULL;
+        threadMutexUnlock(&loading->mutex);
+        loading++;
+        break;
+
+      case ASSET_ENTRY_STATE_ERROR:
+        threadMutexUnlock(&loading->mutex);
+        errorThrow("Failed to load asset asynchronously.");
+        break;
+
+      default:
+        threadMutexUnlock(&loading->mutex);
+        loading++;
+        continue;
+    }
+  } while(loading < ASSET.loading + ASSET_LOADING_COUNT_MAX);
+
+
+  // Reap entries that have no external locks (refs.count == 1 means only the
+  // system hold remains). Only safe to reap LOADED and NOT_STARTED states —
+  // mid-load entries are left for the next cycle.
+  entry = ASSET.entries;
+  do {
+    if(entry->state != ASSET_ENTRY_STATE_LOADED) {
+      entry++;
+      continue;
+    }
+
+    if(entry->type == ASSET_LOADER_TYPE_NULL) {
+      entry++;
+      continue;
+    }
+
+    if(entry->refs.count > 0) {
+      entry++;
+      continue;
+    }
+
+    consolePrint("Reaping asset %s", entry->name);
+    errorChain(assetEntryDispose(entry));
+    entry++;
+  } while(entry < ASSET.entries + ASSET_ENTRY_COUNT_MAX);
+
+  errorOk();
+}
+
+void assetUpdateAsync(thread_t *thread) {
+  while(!threadShouldStop(thread)) {
+    // Walk over each asset
+    assetloading_t *loading;
+    loading = ASSET.loading;
+    
+    do {
+      threadMutexLock(&loading->mutex);
+
+      if(loading->entry == NULL) {
+        threadMutexUnlock(&loading->mutex);
+        loading++;
+        continue;
+      }
+
+      switch(loading->entry->state) {
+        case ASSET_ENTRY_STATE_PENDING_ASYNC:
+          loading->entry->state = ASSET_ENTRY_STATE_LOADING_ASYNC;
+          assertNotNull(
+            ASSET_LOADER_CALLBACKS[loading->type].loadAsync,
+            "Loader does not support async loading."
+          );
+          errorret_t ret = (
+            ASSET_LOADER_CALLBACKS[loading->type].loadAsync(loading)
+          );
+
+          if(errorIsNotOk(ret)) {
+            errorCatch(errorPrint(ret));
+            assertTrue(
+              loading->entry->state == ASSET_ENTRY_STATE_ERROR,
+              "Loader did not set entry state to error on failed load."
+            );
+          }
+
+          threadMutexUnlock(&loading->mutex);
+          loading++;
+          break;
+
+        case ASSET_ENTRY_STATE_LOADING_ASYNC:
+          assertUnreachable(
+            "Entry is in a pending async state still?"
+          );
+          break;
+
+        default:
+          threadMutexUnlock(&loading->mutex);
+          loading++;
+          continue;
+      }
+    } while(loading < ASSET.loading + ASSET_LOADING_COUNT_MAX);
+
+    if(threadShouldStop(thread)) break;
+    usleep(1000);
+  }
+}
+
 errorret_t assetDispose(void) {
+  threadStop(&ASSET.loadThread);
+
+  for(size_t i = 0; i < ASSET_LOADING_COUNT_MAX; i++) {
+    threadMutexDispose(&ASSET.loading[i].mutex);
+  }
+
+  // Cleanup zip file.
   if(ASSET.zip != NULL) {
     if(zip_close(ASSET.zip) != 0) {
       errorThrow("Failed to close asset zip archive.");

src/dusk/asset/asset.h

@@ -9,6 +9,9 @@
 #include "error/error.h"
 #include "asset/assetplatform.h"
 #include "assetfile.h"
+#include "thread/thread.h"
+#include "asset/loader/assetentry.h"
+#include "asset/loader/assetloading.h"
 
 #ifndef assetInitPlatform
   #error "Platform must define assetInitPlatform function."
@@ -20,15 +23,27 @@
 #define ASSET_FILE_NAME "dusk.dsk"
 #define ASSET_HEADER_SIZE 3
 
+#define ASSET_LOADING_COUNT_MAX 4
+#define ASSET_ENTRY_COUNT_MAX 128
+
 typedef struct asset_s {
   zip_t *zip;
   assetplatform_t platform;
+
+  // Background loading thread.
+  thread_t loadThread;
+
+  // Assets that are mid loading.
+  assetloading_t loading[ASSET_LOADING_COUNT_MAX];
+  assetentry_t entries[ASSET_ENTRY_COUNT_MAX];
 } asset_t;
 
 extern asset_t ASSET;
 
 /**
  * Initializes the asset system.
+ * 
+ * @return An error code if the asset system could not be initialized properly.
  */
 errorret_t assetInit(void);
 
@@ -41,21 +56,74 @@ errorret_t assetInit(void);
 bool_t assetFileExists(const char_t *filename);
 
 /**
- * Loads an asset by its filename,
+ * Gets, or creates, a new asset entry. Internal — prefer assetLock.
  *
- * @param filename The filename of the asset to retrieve.
+ * @param name Filename of the asset.
- * @param loader Loader to use for loading the asset file.
+ * @param type Type of the asset.
- * @param params Parameters to pass to the loader.
+ * @param input Loader-specific parameters.
- * @param output The output pointer to store the loaded asset data.
- * @return An error code if the asset could not be loaded.
  */
-errorret_t assetLoad(
+assetentry_t * assetGetEntry(
-  const char_t *filename,
+  const char_t *name,
-  assetfileloader_t loader,
+  const assetloadertype_t type,
-  void *params,
+  assetloaderinput_t *input
-  void *output
 );
 
+/**
+ * Gets, creates, and locks an asset entry. The asset will begin loading on
+ * the next assetUpdate. Call assetUnlock when done to allow the entry to be
+ * reclaimed.
+ *
+ * @param name Filename of the asset.
+ * @param type Type of the asset.
+ * @param input Loader-specific parameters.
+ * @return The locked asset entry.
+ */
+assetentry_t * assetLock(
+  const char_t *name,
+  const assetloadertype_t type,
+  assetloaderinput_t *input
+);
+
+/**
+ * Releases a lock on an asset entry by name. When all locks are released the
+ * entry will be reclaimed at the start of the next assetUpdate.
+ *
+ * @param name Filename of the asset to unlock.
+ */
+void assetUnlock(const char_t *name);
+
+/**
+ * Releases a lock on an asset entry by pointer. When all locks are released
+ * the entry will be reclaimed at the start of the next assetUpdate.
+ *
+ * @param entry The asset entry to unlock.
+ */
+void assetUnlockEntry(assetentry_t *entry);
+
+/**
+ * Requires an asset entry to be loaded. This will block until the asset entry
+ * is fully loaded.
+ * 
+ * @param entry The asset entry to require.
+ * @return An error code if the asset entry could not be loaded properly.
+ */
+errorret_t assetRequireLoaded(assetentry_t *entry);
+
+/**
+ * Updates the asset system.
+ *
+ * @return An error code if the asset system could not be updated properly.
+ */
+errorret_t assetUpdate(void);
+
+/**
+ * Starts the background asset loading thread. The thread runs assetUpdate
+ * in a loop with a short sleep until stopped.
+ * 
+ * @param thread The thread runner.
+ */
+void assetUpdateAsync(thread_t *thread);
+
 /**
  * Disposes/cleans up the asset system.
  * 

src/dusk/asset/assetbatch.c

@@ -0,0 +1,94 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#include "assetbatch.h"
+#include "asset.h"
+#include "assert/assert.h"
+#include "util/memory.h"
+#include <unistd.h>
+
+void assetBatchInit(
+  assetbatch_t *batch,
+  const uint16_t count,
+  const assetbatchdesc_t *descs
+) {
+  assertNotNull(batch, "Batch cannot be NULL.");
+  assertNotNull(descs, "Descs cannot be NULL.");
+  assertTrue(count > 0, "Count must be greater than 0.");
+  assertTrue(count <= ASSET_BATCH_COUNT_MAX, "Count exceeds ASSET_BATCH_COUNT_MAX.");
+
+  memoryZero(batch, sizeof(assetbatch_t));
+  batch->count = count;
+
+  for(uint16_t i = 0; i < count; i++) {
+    // Copy input into batch-owned storage so the descriptor need not persist.
+    batch->inputs[i] = descs[i].input;
+    batch->entries[i] = assetLock(descs[i].path, descs[i].type, &batch->inputs[i]);
+  }
+}
+
+void assetBatchLock(assetbatch_t *batch) {
+  assertNotNull(batch, "Batch cannot be NULL.");
+  for(uint16_t i = 0; i < batch->count; i++) {
+    assetEntryLock(batch->entries[i]);
+  }
+}
+
+void assetBatchUnlock(assetbatch_t *batch) {
+  assertNotNull(batch, "Batch cannot be NULL.");
+  for(uint16_t i = 0; i < batch->count; i++) {
+    assetEntryUnlock(batch->entries[i]);
+  }
+}
+
+bool_t assetBatchIsLoaded(const assetbatch_t *batch) {
+  assertNotNull(batch, "Batch cannot be NULL.");
+  for(uint16_t i = 0; i < batch->count; i++) {
+    if(batch->entries[i]->state != ASSET_ENTRY_STATE_LOADED) return false;
+  }
+  return true;
+}
+
+bool_t assetBatchHasError(const assetbatch_t *batch) {
+  assertNotNull(batch, "Batch cannot be NULL.");
+  for(uint16_t i = 0; i < batch->count; i++) {
+    if(batch->entries[i]->state == ASSET_ENTRY_STATE_ERROR) return true;
+  }
+  return false;
+}
+
+errorret_t assetBatchRequireLoaded(assetbatch_t *batch) {
+  assertNotNull(batch, "Batch cannot be NULL.");
+
+  bool_t allDone;
+  do {
+    allDone = true;
+    for(uint16_t i = 0; i < batch->count; i++) {
+      const assetentrystate_t state = batch->entries[i]->state;
+      if(state == ASSET_ENTRY_STATE_ERROR) {
+        errorThrow("Asset '%s' failed to load.", batch->entries[i]->name);
+      }
+      if(state != ASSET_ENTRY_STATE_LOADED) {
+        allDone = false;
+      }
+    }
+    if(!allDone) {
+      usleep(1000);
+      errorChain(assetUpdate());
+    }
+  } while(!allDone);
+
+  errorOk();
+}
+
+void assetBatchDispose(assetbatch_t *batch) {
+  assertNotNull(batch, "Batch cannot be NULL.");
+  for(uint16_t i = 0; i < batch->count; i++) {
+    assetUnlockEntry(batch->entries[i]);
+  }
+  memoryZero(batch, sizeof(assetbatch_t));
+}

src/dusk/asset/assetbatch.h

@@ -0,0 +1,82 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#pragma once
+#include "asset/loader/assetentry.h"
+#include "asset/loader/assetloader.h"
+
+#define ASSET_BATCH_COUNT_MAX 64
+
+typedef struct {
+  const char_t *path;
+  assetloadertype_t type;
+  assetloaderinput_t input;
+} assetbatchdesc_t;
+
+typedef struct {
+  assetentry_t *entries[ASSET_BATCH_COUNT_MAX];
+  assetloaderinput_t inputs[ASSET_BATCH_COUNT_MAX];
+  uint16_t count;
+} assetbatch_t;
+
+/**
+ * Initialises the batch from an array of descriptors. Each entry is locked
+ * and queued for loading immediately.
+ *
+ * @param batch  Batch to initialise.
+ * @param descs  Array of entry descriptors (need not outlive this call).
+ * @param count  Number of descriptors (must be <= ASSET_BATCH_COUNT_MAX).
+ */
+void assetBatchInit(
+  assetbatch_t *batch,
+  uint16_t count,
+  const assetbatchdesc_t *descs
+);
+
+/**
+ * Acquires one additional lock on every entry in the batch.
+ *
+ * @param batch Batch to lock.
+ */
+void assetBatchLock(assetbatch_t *batch);
+
+/**
+ * Releases one lock from every entry in the batch. When an entry's lock
+ * count reaches zero it will be reaped on the next assetUpdate.
+ *
+ * @param batch Batch to unlock.
+ */
+void assetBatchUnlock(assetbatch_t *batch);
+
+/**
+ * Returns true if every entry in the batch has finished loading.
+ *
+ * @param batch Batch to query.
+ */
+bool_t assetBatchIsLoaded(const assetbatch_t *batch);
+
+/**
+ * Returns true if any entry in the batch is in an error state.
+ *
+ * @param batch Batch to query.
+ */
+bool_t assetBatchHasError(const assetbatch_t *batch);
+
+/**
+ * Blocks until every entry is loaded. Returns an error if any entry fails.
+ *
+ * @param batch Batch to wait on.
+ */
+errorret_t assetBatchRequireLoaded(assetbatch_t *batch);
+
+/**
+ * Releases the batch's lock on every entry and clears the batch. After this
+ * call the batch struct may be reused with assetBatchInit.
+ *
+ * @param batch Batch to dispose.
+ */
+void assetBatchDispose(assetbatch_t *batch);

src/dusk/asset/assetfile.h

@@ -15,6 +15,7 @@ typedef struct assetfile_s assetfile_t;
 
 typedef errorret_t (*assetfileloader_t)(assetfile_t *file);
 
+// Describes a file not yet loaded.
 typedef struct assetfile_s {
   char_t filename[ASSET_FILE_NAME_MAX];
   void *params;

src/dusk/asset/loader/CMakeLists.txt

@@ -4,8 +4,15 @@
 # https://opensource.org/licenses/MIT
 
 # Sources
+target_sources(${DUSK_LIBRARY_TARGET_NAME}
+  PUBLIC
+    assetentry.c
+    assetloader.c
+)
+
 
 # Subdirs
 add_subdirectory(display)
 add_subdirectory(locale)
 add_subdirectory(json)
+add_subdirectory(script)

src/dusk/asset/loader/assetentry.c

@@ -0,0 +1,73 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ * 
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#include "assetentry.h"
+#include "assert/assert.h"
+#include "util/memory.h"
+#include "util/string.h"
+
+void assetEntryInit(
+  assetentry_t *entry,
+  const char_t *name,
+  const assetloadertype_t type,
+  assetloaderinput_t *input
+) {
+  assertNotNull(entry, "Entry cannot be NULL");
+  assertStrLenMin(name, 1, "Name cannot be empty");
+  assertStrLenMax(name, ASSET_FILE_NAME_MAX - 1, "Name too long");
+  assertTrue(type != ASSET_LOADER_TYPE_NULL, "Invalid loader type.");
+  assertTrue(type < ASSET_LOADER_TYPE_COUNT, "Invalid loader type.");
+
+  memoryZero(entry, sizeof(assetentry_t));
+  stringCopy(entry->name, name, ASSET_FILE_NAME_MAX);
+  entry->type = type;
+  entry->input = input;
+  entry->state = ASSET_ENTRY_STATE_NOT_STARTED;
+  refInit(&entry->refs, entry, NULL, NULL, NULL);
+}
+
+void assetEntryLock(assetentry_t *entry) {
+  assertNotNull(entry, "Entry cannot be NULL");
+  assertTrue(entry->type != ASSET_LOADER_TYPE_NULL, "Invalid loader type.");
+  refLock(&entry->refs);
+}
+
+void assetEntryUnlock(assetentry_t *entry) {
+  assertNotNull(entry, "Entry cannot be NULL");
+  assertTrue(entry->type != ASSET_LOADER_TYPE_NULL, "Invalid loader type.");
+  refUnlock(&entry->refs);
+}
+
+void assetEntryStartLoading(
+  assetentry_t *entry,
+  assetloading_t *loading
+) {
+  assertNotNull(entry, "Entry cannot be NULL");
+  assertNotNull(loading, "Loading cannot be NULL");
+  assertTrue(entry->type != ASSET_LOADER_TYPE_NULL, "Invalid loader type.");
+  assertTrue(
+    entry->state == ASSET_ENTRY_STATE_NOT_STARTED,
+    "Can only start loading from NOT_STARTED state."
+  );
+
+  entry->state = ASSET_ENTRY_STATE_PENDING_SYNC;
+  memoryZero(&loading->loading, sizeof(assetloaderloading_t));
+  loading->type = entry->type;
+  loading->entry = entry;
+  // At this point the asset manager will manage this thing's loading
+}
+
+errorret_t assetEntryDispose(assetentry_t *entry) {
+  assertNotNull(entry, "Entry cannot be NULL");
+
+  assertTrue(entry->type != ASSET_LOADER_TYPE_NULL, "Invalid loader type.");
+  assertTrue(entry->type < ASSET_LOADER_TYPE_COUNT, "Invalid loader type.");
+  
+  errorChain(ASSET_LOADER_CALLBACKS[entry->type].dispose(entry));
+  memoryZero(entry, sizeof(assetentry_t));
+  errorOk();
+}

src/dusk/asset/loader/assetentry.h

@@ -0,0 +1,86 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ * 
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#pragma once
+#include "asset/loader/assetloading.h"
+#include "util/ref.h"
+
+typedef enum {
+  ASSET_ENTRY_STATE_NOT_STARTED,
+  ASSET_ENTRY_STATE_PENDING_ASYNC,
+  ASSET_ENTRY_STATE_LOADING_ASYNC,
+  ASSET_ENTRY_STATE_PENDING_SYNC,
+  ASSET_ENTRY_STATE_LOADING_SYNC,
+  ASSET_ENTRY_STATE_LOADED,
+  ASSET_ENTRY_STATE_ERROR
+} assetentrystate_t;
+
+typedef struct assetentry_s {
+  // Filename and cache key
+  char_t name[ASSET_FILE_NAME_MAX];
+  // What type of asset is this?
+  assetloadertype_t type;
+  // Data
+  assetloaderoutput_t data;
+  // What state is this asset entry in currently?
+  assetentrystate_t state;
+  // What is referencing this asset entry.
+  ref_t refs;
+  // Data that will be passed to the loader about how it should load.
+  assetloaderinput_t *input;
+} assetentry_t;
+
+/**
+ * Initializes an asset entry with the given name and type. This does not load
+ * the asset.
+ * 
+ * @param entry The asset entry to initialize.
+ * @param name The name of the asset, used as a key for loading and caching.
+ * @param type The type of asset this entry represents.
+ * @param input Data that will be passed to the loader about how it should load.
+ */
+void assetEntryInit(
+  assetentry_t *entry,
+  const char_t *name,
+  const assetloadertype_t type,
+  assetloaderinput_t *input
+);
+
+/**
+ * Locks an asset entry, preventing it from being freed until it is unlocked.
+ * 
+ * @param entry The asset entry to lock.
+ */
+void assetEntryLock(assetentry_t *entry);
+
+/**
+ * Unlocks an asset entry, allowing it to be freed if there are no more locks.
+ * 
+ * @param entry The asset entry to unlock.
+ */
+void assetEntryUnlock(assetentry_t *entry);
+
+/**
+ * Starts loading the given asset entry using an assetloading slot. This will
+ * be called by the asset manager when it deems it's a good time to begin the
+ * loading of this asset entry.
+ * 
+ * Currently we return the error but in future this will not be returned.
+ * 
+ * @param entry The asset entry to start loading.
+ * @param loading The assetloading slot to use for loading this asset entry.
+ * @return Any error that occurs during loading.
+ */
+void assetEntryStartLoading(assetentry_t *entry, assetloading_t *loading);
+
+/**
+ * Disposes an asset entry, freeing any resources it holds.
+ * 
+ * @param entry The asset entry to dispose.
+ * @return Any error that occurs during disposal.
+ */
+errorret_t assetEntryDispose(assetentry_t *entry);

src/dusk/asset/loader/assetloader.c

@@ -0,0 +1,48 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#include "assetloader.h"
+
+assetloadercallbacks_t ASSET_LOADER_CALLBACKS[ASSET_LOADER_TYPE_COUNT] = {
+  [ASSET_LOADER_TYPE_NULL] = { 0 },
+
+  [ASSET_LOADER_TYPE_MESH] = {
+    .loadSync = assetMeshLoaderSync,
+    .loadAsync = assetMeshLoaderAsync,
+    .dispose = assetMeshDispose
+  },
+
+  [ASSET_LOADER_TYPE_TEXTURE] = {
+    .loadSync = assetTextureLoaderSync,
+    .loadAsync = assetTextureLoaderAsync,
+    .dispose = assetTextureDispose
+  },
+
+  [ASSET_LOADER_TYPE_TILESET] = {
+    .loadSync = assetTilesetLoaderSync,
+    .loadAsync = assetTilesetLoaderAsync,
+    .dispose = assetTilesetDispose
+  },
+
+  [ASSET_LOADER_TYPE_LOCALE] = {
+    .loadSync = assetLocaleLoaderSync,
+    .loadAsync = assetLocaleLoaderAsync,
+    .dispose = assetLocaleDispose
+  },
+
+  [ASSET_LOADER_TYPE_JSON] = {
+    .loadSync = assetJsonLoaderSync,
+    .loadAsync = assetJsonLoaderAsync,
+    .dispose = assetJsonDispose
+  },
+
+  [ASSET_LOADER_TYPE_SCRIPT] = {
+    .loadSync = assetScriptLoaderSync,
+    .loadAsync = assetScriptLoaderAsync,
+    .dispose = assetScriptDispose
+  },
+};

src/dusk/asset/loader/assetloader.h

@@ -0,0 +1,96 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ * 
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#pragma once
+#include "asset/loader/display/assetmeshloader.h"
+#include "asset/loader/display/assettextureloader.h"
+#include "asset/loader/display/assettilesetloader.h"
+#include "asset/loader/locale/assetlocaleloader.h"
+#include "asset/loader/json/assetjsonloader.h"
+#include "asset/loader/script/assetscriptloader.h"
+
+typedef enum {
+  ASSET_LOADER_TYPE_NULL,
+
+  ASSET_LOADER_TYPE_MESH,
+  ASSET_LOADER_TYPE_TEXTURE,
+  ASSET_LOADER_TYPE_TILESET,
+  ASSET_LOADER_TYPE_LOCALE,
+  ASSET_LOADER_TYPE_JSON,
+  ASSET_LOADER_TYPE_SCRIPT,
+
+  ASSET_LOADER_TYPE_COUNT
+} assetloadertype_t;
+
+typedef union {
+  assetmeshloaderinput_t mesh;
+  assettextureloaderinput_t texture;
+  assettilesetloaderinput_t tileset;
+  assetlocaleloaderinput_t locale;
+  assetjsonloaderinput_t json;
+  assetscriptloaderinput_t script;
+} assetloaderinput_t;
+
+typedef union {
+  assetmeshloaderloading_t mesh;
+  assettextureloaderloading_t texture;
+  assettilesetloaderloading_t tileset;
+  assetlocaleloaderloading_t locale;
+  assetjsonloaderloading_t json;
+  assetscriptloaderloading_t script;
+} assetloaderloading_t;
+
+typedef union {
+  assetmeshoutput_t mesh;
+  assettextureoutput_t texture;
+  assettilesetoutput_t tileset;
+  assetlocaleoutput_t locale;
+  assetjsonoutput_t json;
+  assetscriptoutput_t script;
+} assetloaderoutput_t;
+
+typedef struct assetloading_s assetloading_t;
+typedef struct assetentry_s assetentry_t;
+
+typedef errorret_t (assetloadersynccallback_t)(assetloading_t *loading);
+typedef errorret_t (assetloaderasynccallback_t)(assetloading_t *loading);
+typedef errorret_t (assetloaderdisposecallback_t)(assetentry_t *entry);
+
+typedef struct {
+  assetloadersynccallback_t *loadSync;
+  assetloaderasynccallback_t *loadAsync;
+  assetloaderdisposecallback_t *dispose;
+} assetloadercallbacks_t;
+
+extern assetloadercallbacks_t ASSET_LOADER_CALLBACKS[ASSET_LOADER_TYPE_COUNT];
+
+/**
+ * Shorthand method to both chain an error (against the loader state) and to
+ * set the asset entry state to error.
+ * 
+ * @param loading The asset loading slot.
+ * @param ret The error return value to check and chain if it's an error.
+ */
+#define assetLoaderErrorChain(loading, _expr) {\
+  errorret_t _alec = (_expr); \
+  if(errorIsNotOk(_alec)) { \
+    (loading)->entry->state = ASSET_ENTRY_STATE_ERROR; \
+    errorChain(_alec); \
+  } \
+}
+
+/**
+ * Shorthand method to both throw an error (against the loader state) and to
+ * set the asset entry state to error.
+ * 
+ * @param loading The asset loading slot.
+ * @param ... Format string and arguments for the error message.
+ */
+#define assetLoaderErrorThrow(loading, ...) {\
+  loading->entry->state = ASSET_ENTRY_STATE_ERROR; \
+  errorThrow(__VA_ARGS__); \
+}

src/dusk/asset/loader/assetloading.h

@@ -0,0 +1,30 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ * 
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#pragma once
+#include "assetloader.h"
+#include "asset/assetfile.h"
+#include "thread/threadmutex.h"
+
+typedef struct assetentry_s assetentry_t;
+
+typedef struct assetloading_s {
+  // Protects entry pointer and entry->state from concurrent access.
+  threadmutex_t mutex;
+  // What type of asset is being loaded.
+  assetloadertype_t type;
+  // Referral back to the asset entry that will be kept alive after load done.
+  assetentry_t *entry;
+  // Information used during the load operation only.
+  assetloaderloading_t loading;
+} assetloading_t;
+
+typedef errorret_t (assetloadingcallback_t)(assetloading_t *loading);
+
+typedef struct {
+  assetloadingcallback_t *loadSync;
+} assetloadingcallbacks_t;

src/dusk/asset/loader/display/assetmeshloader.c

@@ -5,178 +5,170 @@
  * https://opensource.org/licenses/MIT
  */
 
-#include "asset/loader/display/assetmeshloader.h"
+#include "assetmeshloader.h"
-#include "asset/asset.h"
 #include "assert/assert.h"
 #include "util/endian.h"
 #include "util/memory.h"
+#include "asset/loader/assetloading.h"
+#include "asset/loader/assetentry.h"
 
-errorret_t assetMeshLoader(assetfile_t *file) {
+errorret_t assetMeshLoaderAsync(assetloading_t *loading) {
-  assertNotNull(file, "Asset file cannot be null");
+  assertNotNull(loading, "Loading cannot be NULL");
 
-  assetmeshoutput_t *output = (assetmeshoutput_t *)file->output;
+  if(loading->loading.mesh.state != ASSET_MESH_LOADING_STATE_READ_FILE) {
-  assertNotNull(output, "Output cannot be null");
+    errorOk();
-  assertNotNull(output->outMesh, "Output mesh cannot be null");
+  }
-  assertNotNull(output->outVertices, "Output vertices cannot be null");
 
-  // STL file loading
+  assetmeshoutput_t *out = &loading->entry->data.mesh;
-  errorChain(assetFileOpen(file));
+  assetfile_t *file = &loading->loading.mesh.file;
+  assetmeshinputaxis_t axis = loading->entry->input->mesh;
 
-  // Skip the 80 byte header
+  assetLoaderErrorChain(loading, assetFileInit(file, loading->entry->name, NULL, NULL));
-  errorChain(assetFileRead(file, NULL, 80));
+  assetLoaderErrorChain(loading, assetFileOpen(file));
-  if(file->lastRead != 80) errorThrow("Failed to skip STL header");
+
+  // Skip the 80-byte STL header.
+  assetLoaderErrorChain(loading, assetFileRead(file, NULL, 80));
+  if(file->lastRead != 80) {
+    assetLoaderErrorThrow(loading, "Failed to skip STL header.");
+  }
 
   uint32_t triangleCount;
-  errorChain(assetFileRead(file, &triangleCount, sizeof(uint32_t)));
+  assetLoaderErrorChain(loading, assetFileRead(file, &triangleCount, sizeof(uint32_t)));
-  if(file->lastRead != sizeof(uint32_t)) errorThrow("Failed read tri count");
+  if(file->lastRead != sizeof(uint32_t)) {
-  // normalize
+    assetLoaderErrorThrow(loading, "Failed to read tri count");
+  }
   triangleCount = endianLittleToHost32(triangleCount);
 
-  // Allocate mesh and vertex data
+  out->vertices = memoryAllocate(sizeof(meshvertex_t) * triangleCount * 3);
-  errorret_t ret;
+  meshvertex_t *verts = out->vertices;
-  meshvertex_t *verts = memoryAllocate(
-    sizeof(meshvertex_t) * triangleCount * 3
-  );
-  *output->outVertices = verts;
 
-  // Read triangle data
+  errorret_t ret;
   for(uint32_t i = 0; i < triangleCount; i++) {
     assetmeshstltriangle_t triData;
     ret = assetFileRead(file, &triData, sizeof(triData));
-    if(ret.code != ERROR_OK) {
+    if(errorIsNotOk(ret)) {
       memoryFree(verts);
-      errorChain(ret);
+      out->vertices = NULL;
+      assetLoaderErrorChain(loading, ret);
     }
-
     if(file->lastRead != sizeof(triData)) {
       memoryFree(verts);
-      errorThrow("Failed to read triangle data");
+      out->vertices = NULL;
+      assetLoaderErrorThrow(loading, "Failed to read triangle data");
     }
 
-    // Skip normals, we don't use them
-
-    // Fix endianess of of data
     for(uint8_t j = 0; j < 3; j++) {
       #if MESH_ENABLE_COLOR
-        verts[i * 3 + j].color.r = (uint8_t)(endianLittleToHostFloat(
+        verts[i * 3 + j].color.r = (
-          triData.normal[0]
+          (uint8_t)(endianLittleToHostFloat(triData.normal[0]) * 255.0f)
-        ) * 255.0f);
+        );
-        verts[i * 3 + j].color.g = (uint8_t)(endianLittleToHostFloat(
+        verts[i * 3 + j].color.g = (
-          triData.normal[1]
+          (uint8_t)(endianLittleToHostFloat(triData.normal[1]) * 255.0f)
-        ) * 255.0f);
+        );
-        verts[i * 3 + j].color.b = (uint8_t)(endianLittleToHostFloat(
+        verts[i * 3 + j].color.b = (
-          triData.normal[2]
+          (uint8_t)(endianLittleToHostFloat(triData.normal[2]) * 255.0f)
-        ) * 255.0f);
+        );
         verts[i * 3 + j].color.a = 0xFF;
       #endif
 
-      verts[i * 3 + j].uv[0] = 0.0f; // No UV data in STL, just set to 0
+      verts[i * 3 + j].uv[0] = 0.0f;
       verts[i * 3 + j].uv[1] = 0.0f;
 
       for(uint8_t k = 0; k < 3; k++) {
-        verts[i * 3 + j].pos[k] = endianLittleToHostFloat(
+        verts[i * 3 + j].pos[k] = endianLittleToHostFloat(triData.positions[j][k]);
-          triData.positions[j][k]
-        );
       }
 
-      switch(output->inputAxis) {
+      switch(axis) {
-        case MESH_INPUT_AXIS_Z_UP:
+        case MESH_INPUT_AXIS_Z_UP: {
-          // Convert Z-Up to Y-Up
+          float_t temp = verts[i * 3 + j].pos[1];
-          {
+          verts[i * 3 + j].pos[1] = verts[i * 3 + j].pos[2];
-            float_t temp = verts[i * 3 + j].pos[1];
+          verts[i * 3 + j].pos[2] = temp;
-            verts[i * 3 + j].pos[1] = verts[i * 3 + j].pos[2];
-            verts[i * 3 + j].pos[2] = temp;
-          }
           break;
-
+        }
-        case MESH_INPUT_AXIS_X_UP:
+        case MESH_INPUT_AXIS_X_UP: {
-          // Convert X-Up to Y-Up
+          float_t temp = verts[i * 3 + j].pos[0];
-          {
+          verts[i * 3 + j].pos[0] = verts[i * 3 + j].pos[1];
-            float_t temp = verts[i * 3 + j].pos[0];
+          verts[i * 3 + j].pos[1] = temp;
-            verts[i * 3 + j].pos[0] = verts[i * 3 + j].pos[1];
-            verts[i * 3 + j].pos[1] = temp;
-          }
           break;
-
+        }
         case MESH_INPUT_AXIS_Y_DOWN:
-          // Invert Y axis
           verts[i * 3 + j].pos[1] = -verts[i * 3 + j].pos[1];
           break;
-
+        case MESH_INPUT_AXIS_Z_DOWN: {
-        case MESH_INPUT_AXIS_Z_DOWN:
+          float_t temp = verts[i * 3 + j].pos[1];
-          // Convert Z-Up to Y-Up and invert Y axis
+          verts[i * 3 + j].pos[1] = -verts[i * 3 + j].pos[2];
-          {
+          verts[i * 3 + j].pos[2] = temp;
-            float_t temp = verts[i * 3 + j].pos[1];
-            verts[i * 3 + j].pos[1] = -verts[i * 3 + j].pos[2];
-            verts[i * 3 + j].pos[2] = temp;
-          }
           break;
-
+        }
-        case MESH_INPUT_AXIS_X_DOWN:
+        case MESH_INPUT_AXIS_X_DOWN: {
-          // Convert X-Up to Y-Up and invert Y axis
+          float_t temp = verts[i * 3 + j].pos[0];
-          {
+          verts[i * 3 + j].pos[0] = verts[i * 3 + j].pos[1];
-            float_t temp = verts[i * 3 + j].pos[0];
+          verts[i * 3 + j].pos[1] = -temp;
-            verts[i * 3 + j].pos[0] = verts[i * 3 + j].pos[1];
-            verts[i * 3 + j].pos[1] = -temp;
-          }
           break;
-
+        }
         case MESH_INPUT_AXIS_Y_UP:
         default:
-          // No covnersion possible / Needed
           break;
       }
     }
   }
 
-  // Finally, init mesh
-  ret = meshInit(
-    output->outMesh,
-    MESH_PRIMITIVE_TYPE_TRIANGLES,
-    triangleCount * 3,
-    verts
-  );
-  if(ret.code != ERROR_OK) {
-    memoryFree(verts);
-    errorChain(ret);
-  }
-
   ret = assetFileClose(file);
-  if(ret.code != ERROR_OK) {
+  if(errorIsNotOk(ret)) {
-    errorCatch(errorPrint(meshDispose(output->outMesh)));
     memoryFree(verts);
-    errorChain(ret);
+    out->vertices = NULL;
+    assetLoaderErrorChain(loading, ret);
   }
+  assetFileDispose(file);
 
+  loading->loading.mesh.triangleCount = triangleCount;
+  loading->loading.mesh.state = ASSET_MESH_LOADING_STATE_CREATE_MESH;
+  loading->entry->state = ASSET_ENTRY_STATE_PENDING_SYNC;
   errorOk();
 }
 
-errorret_t assetMeshLoadToOutput(
+errorret_t assetMeshLoaderSync(assetloading_t *loading) {
-  const char_t *path,
+  assertNotNull(loading, "Loading cannot be NULL");
-  assetmeshoutput_t *output
+  assertTrue(loading->type == ASSET_LOADER_TYPE_MESH, "Invalid type.");
-) {
-  assertNotNull(path, "Path cannot be null");
-  assertNotNull(output, "Output cannot be null");
-  assertNotNull(output->outMesh, "Output mesh cannot be null");
-  assertNotNull(output->outVertices, "Output vertices cannot be null");
 
-  return assetLoad(path, &assetMeshLoader, NULL, output);
+  switch(loading->loading.mesh.state) {
+    case ASSET_MESH_LOADING_STATE_INITIAL:
+      loading->loading.mesh.state = ASSET_MESH_LOADING_STATE_READ_FILE;
+      loading->entry->state = ASSET_ENTRY_STATE_PENDING_ASYNC;
+      errorOk();
+      break;
+
+    case ASSET_MESH_LOADING_STATE_CREATE_MESH:
+      break;
+
+    default:
+      errorOk();
+  }
+
+  assetmeshoutput_t *out = &loading->entry->data.mesh;
+  assertNotNull(out->vertices, "Mesh vertices should have been loaded by now.");
+
+  errorret_t ret = meshInit(
+    &out->mesh,
+    MESH_PRIMITIVE_TYPE_TRIANGLES,
+    loading->loading.mesh.triangleCount * 3,
+    out->vertices
+  );
+  if(errorIsNotOk(ret)) {
+    loading->entry->state = ASSET_ENTRY_STATE_ERROR;
+    memoryFree(out->vertices);
+    out->vertices = NULL;
+    assetLoaderErrorChain(loading, ret);
+  }
+
+  loading->entry->state = ASSET_ENTRY_STATE_LOADED;
+  errorOk();
 }
 
-errorret_t assetMeshLoad(
+errorret_t assetMeshDispose(assetentry_t *entry) {
-  const char_t *path,
+  assertNotNull(entry, "Asset entry cannot be NULL");
-  mesh_t *outMesh,
+  assertTrue(entry->type == ASSET_LOADER_TYPE_MESH, "Invalid type.");
-  meshvertex_t **outVertices,
+  errorChain(meshDispose(&entry->data.mesh.mesh));
-  const assetmeshinputaxis_t inputAxis
+  memoryFree(entry->data.mesh.vertices);
-) {
+  errorOk();
-  assertNotNull(path, "Path cannot be null");
-  assertNotNull(outMesh, "Output mesh cannot be null");
-  assertNotNull(outVertices, "Output vertices cannot be null");
-  
-  assetmeshoutput_t output = {
-    outMesh,
-    outVertices,
-    inputAxis
-  };
-  return assetMeshLoadToOutput(path, &output);
 }

src/dusk/asset/loader/display/assetmeshloader.h

@@ -6,12 +6,15 @@
  */
 
 #pragma once
-#include "asset/asset.h"
+#include "asset/assetfile.h"
 #include "display/mesh/mesh.h"
 #include "assert/assert.h"
 
+typedef struct assetloading_s assetloading_t;
+typedef struct assetentry_s assetentry_t;
+
 typedef enum {
-  MESH_INPUT_AXIS_Y_UP,// Default
+  MESH_INPUT_AXIS_Y_UP,
   MESH_INPUT_AXIS_Z_UP,
   MESH_INPUT_AXIS_X_UP,
 
@@ -20,10 +23,24 @@ typedef enum {
   MESH_INPUT_AXIS_X_DOWN,
 } assetmeshinputaxis_t;
 
+typedef assetmeshinputaxis_t assetmeshloaderinput_t;
+
+typedef enum {
+  ASSET_MESH_LOADING_STATE_INITIAL,
+  ASSET_MESH_LOADING_STATE_READ_FILE,
+  ASSET_MESH_LOADING_STATE_CREATE_MESH,
+  ASSET_MESH_LOADING_STATE_DONE
+} assetmeshloadingstate_t;
+
 typedef struct {
-  mesh_t *outMesh;
+  assetfile_t file;
-  meshvertex_t **outVertices;
+  assetmeshloadingstate_t state;
-  assetmeshinputaxis_t inputAxis;
+  uint32_t triangleCount;
+} assetmeshloaderloading_t;
+
+typedef struct {
+  mesh_t mesh;
+  meshvertex_t *vertices;
 } assetmeshoutput_t;
 
 #pragma pack(push, 1)
@@ -36,26 +53,6 @@ typedef struct {
 
 assertStructSize(assetmeshstltriangle_t, 50);
 
-/**
+errorret_t assetMeshLoaderAsync(assetloading_t *loading);
- * Loader for mesh assets.
+errorret_t assetMeshLoaderSync(assetloading_t *loading);
- * 
+errorret_t assetMeshDispose(assetentry_t *entry);
- * @param file Asset file to load the mesh from.
- * @return Any error that occurs during loading.
- */
-errorret_t assetMeshLoader(assetfile_t *file);
-
-/**
- * Handler for mesh assets.
- * 
- * @param file Asset file to load the mesh from.
- * @param outMesh Output mesh to load the data into.
- * @param outVertices Output pointer to the vertex data, used for cleanup.
- * @param inputAxis The axis orientation of the input mesh data.
- * @return Any error that occurs during loading.
- */
-errorret_t assetMeshLoad(
-  const char_t *path,
-  mesh_t *outMesh,
-  meshvertex_t **outVertices,
-  const assetmeshinputaxis_t inputAxis
-);

src/dusk/asset/loader/display/assettextureloader.c

@@ -11,6 +11,8 @@
 #include "stb_image.h"
 #include "log/log.h"
 #include "util/endian.h"
+#include "asset/loader/assetloading.h"
+#include "asset/loader/assetentry.h"
 
 stbi_io_callbacks ASSET_TEXTURE_STB_CALLBACKS = {
   .read = assetTextureReader,
@@ -25,7 +27,7 @@ int assetTextureReader(void *user, char *data, int size) {
   assertNotNull(file, "Asset file in stb_image callbacks cannot be NULL.");
   
   errorret_t ret = assetFileRead(file, data, (size_t)size);
-  if(ret.code != ERROR_OK) {
+  if(errorIsNotOk(ret)) {
     errorCatch(errorPrint(ret));
     return -1;
   }
@@ -38,7 +40,7 @@ void assetTextureSkipper(void *user, int n) {
   assertNotNull(file, "Asset file in stb_image callbacks cannot be NULL.");
 
   errorret_t ret = assetFileRead(file, NULL, (size_t)n);
-  if(ret.code != ERROR_OK) {
+  if(errorIsNotOk(ret)) {
     errorCatch(errorPrint(ret));
   }
 }
@@ -50,66 +52,114 @@ int assetTextureEOF(void *user) {
   return file->position >= file->size;
 }
 
-errorret_t assetTextureLoader(assetfile_t *file) {
+errorret_t assetTextureLoaderAsync(assetloading_t *loading) {
-  assertNotNull(file, "Asset file cannot be NULL.");
+  assertNotNull(loading, "Loading cannot be NULL");
-  assertNotNull(file->params, "Asset file parameters cannot be NULL.");
-  assertNotNull(file->output, "Asset file output cannot be NULL.");
 
-  assettextureloaderparams_t *p = (assettextureloaderparams_t*)file->params;
+  // Only care about loading pixels.
-  assertNotNull(p, "Asset texture loader parameters cannot be NULL.");
+  if(loading->loading.texture.state != ASSET_TEXTURE_LOADING_STATE_LOAD_PIXELS){
+    errorOk();
+  }
 
+  // Init the file
+  assertNull(
+    loading->loading.texture.data, "Pixels already defined?"
+  );
+
+  assetfile_t *file = &loading->loading.texture.file;
+  assetLoaderErrorChain(loading, assetFileInit(
+    file,
+    loading->entry->name,
+    NULL,
+    &loading->entry->data.texture
+  ));
+  assetLoaderErrorChain(loading, assetFileOpen(file));
+
+  // Determine channels
   int channelsDesired;
-  switch(p->format) {
+  switch(loading->entry->input->texture) {
     case TEXTURE_FORMAT_RGBA:
       channelsDesired = 4;
       break;
 
     default:
-      errorThrow("Bad texture format.");
+      assetLoaderErrorThrow(loading, "Bad texture format.");
   }
 
-  int width, height, channels;
+  // Load image pixels.
-  errorChain(assetFileOpen(file));
+  loading->loading.texture.data = stbi_load_from_callbacks(
-  uint8_t *data = stbi_load_from_callbacks(
     &ASSET_TEXTURE_STB_CALLBACKS,
     file,
-    &width,
+    &loading->loading.texture.width,
-    &height,
+    &loading->loading.texture.height,
-    &channels,
+    &loading->loading.texture.channels,
     channelsDesired
   );
-  errorChain(assetFileClose(file));
 
-  if(data == NULL) {
+  // Close out the file.
+  assetLoaderErrorChain(loading, assetFileClose(file));
+  assetLoaderErrorChain(loading, assetFileDispose(file));
+
+  // Ensure we loaded correctly.
+  if(loading->loading.texture.data == NULL) {
     const char_t *errorStr = stbi_failure_reason();
-    errorThrow("Failed to load texture from file %s.", errorStr);
+    assetLoaderErrorThrow(loading, "Failed to load texture from file %s.", errorStr);
   }
 
   // Fixes a specific bug probably with Dolphin but for now just assuming endian
   if(!isHostLittleEndian()) {
-    stbi__vertical_flip(data, width, height, channelsDesired);
+    stbi__vertical_flip(
+      loading->loading.texture.data,
+      loading->loading.texture.width,
+      loading->loading.texture.height,
+      loading->loading.texture.channels
+    );
   }
 
-  errorChain(textureInit(
+  loading->loading.texture.state = ASSET_TEXTURE_LOADING_STATE_CREATE_TEXTURE;
-    (texture_t*)file->output,
+  loading->entry->state = ASSET_ENTRY_STATE_PENDING_SYNC;
-    (int32_t)width, (int32_t)height,
-    p->format,
-    (texturedata_t){
-      .rgbaColors = (color_t*)data
-    }
-  ));
-
-  stbi_image_free(data);
   errorOk();
 }
 
-errorret_t assetTextureLoad(
+errorret_t assetTextureLoaderSync(assetloading_t *loading) {
-  const char_t *path,
+  assertNotNull(loading, "Loading cannot be NULL");
-  texture_t *out,
+
-  const textureformat_t format
+  switch(loading->loading.texture.state) {
-) {
+    case ASSET_TEXTURE_LOADING_STATE_INITIAL:
-  assettextureloaderparams_t params = {
+      loading->loading.texture.state = ASSET_TEXTURE_LOADING_STATE_LOAD_PIXELS;
-    .format = format
+      loading->entry->state = ASSET_ENTRY_STATE_PENDING_ASYNC;
-  };
+      errorOk();
-  return assetLoad(path, assetTextureLoader, &params, out);
+      break;
+      
+    case ASSET_TEXTURE_LOADING_STATE_CREATE_TEXTURE:
+      break;
+
+    default:
+      errorOk();
+  }
+
+  // Create the texture.
+  assertNotNull(
+    loading->loading.texture.data, "Pixels should have been loaded by now."
+  );
+
+  assetLoaderErrorChain(loading, textureInit(
+    (texture_t*)&loading->entry->data.texture,
+    loading->loading.texture.width,
+    loading->loading.texture.height,
+    loading->entry->input->texture,
+    (texturedata_t){
+      .rgbaColors = (color_t*)loading->loading.texture.data
+    }
+  ));
+
+  // Free the pixels.
+  stbi_image_free(loading->loading.texture.data);
+
+  loading->entry->state = ASSET_ENTRY_STATE_LOADED;
+  errorOk();
+}
+
+errorret_t assetTextureDispose(assetentry_t *entry) {
+  assertNotNull(entry, "Asset entry cannot be NULL");
+  return textureDispose(&entry->data.texture);
 }

src/dusk/asset/loader/display/assettextureloader.h

@@ -6,12 +6,29 @@
  */
 
 #pragma once
-#include "asset/asset.h"
+#include "asset/assetfile.h"
 #include "display/texture/texture.h"
 
+typedef struct assetloading_s assetloading_t;
+typedef struct assetentry_s assetentry_t;
+typedef textureformat_t assettextureloaderinput_t;
+
+typedef enum {
+  ASSET_TEXTURE_LOADING_STATE_INITIAL,
+  ASSET_TEXTURE_LOADING_STATE_LOAD_PIXELS,
+  ASSET_TEXTURE_LOADING_STATE_CREATE_TEXTURE,
+  ASSET_TEXTURE_LOADING_STATE_DONE
+} assettextureloadingstate_t;
+
 typedef struct {
-  textureformat_t format;
+  assetfile_t file;
-} assettextureloaderparams_t;
+  assettextureloadingstate_t state;
+
+  int channels, width, height;
+  uint8_t *data;
+} assettextureloaderloading_t;
+
+typedef texture_t assettextureoutput_t;
 
 /**
  * STB image read callback for asset files.
@@ -23,28 +40,42 @@ typedef struct {
  */
 int assetTextureReader(void *user, char *data, int size);
 
+/**
+ * STB image skip callback for asset files.
+ * 
+ * @param user User data passed to the callback, should be an assetfile_t*.
+ * @param n Number of bytes to skip in the file.
+ */
 void assetTextureSkipper(void *user, int n);
 
+/**
+ * STB image EOF callback for asset files.
+ * 
+ * @param user User data passed to the callback, should be an assetfile_t*.
+ * @return Non-zero if end of file has been reached, zero otherwise.
+ */
 int assetTextureEOF(void *user);
 
 /**
- * Handler for texture assets.
+ * Synchronous loader for texture assets.
  * 
- * @param file Asset file to load the texture from.
+ * @param loading Loading information for the asset being loaded.
- * @return Any error that occurs during loading.
+ * @return Error code indicating success or failure of the load operation.
  */
-errorret_t assetTextureLoader(assetfile_t *file);
+errorret_t assetTextureLoaderAsync(assetloading_t *loading);
 
 /**
- * Loads a texture from the specified path.
+ * Synchronous loader for texture assets.
  * 
- * @param path Path to the texture asset.
+ * @param loading Loading information for the asset being loaded.
- * @param out Output texture to load into.
+ * @return Error code indicating success or failure of the load operation.
- * @param format Format of the texture to load.
- * @return Any error that occurs during loading.
  */
-errorret_t assetTextureLoad(
+errorret_t assetTextureLoaderSync(assetloading_t *loading);
-  const char_t *path,
+
-  texture_t *out,
+/**
-  const textureformat_t format
+ * Disposer for texture assets.
-);
+ * 
+ * @param entry Asset entry containing the texture to dispose.
+ * @return Error code indicating success or failure of the dispose operation.
+ */
+errorret_t assetTextureDispose(assetentry_t *entry);

src/dusk/asset/loader/display/assettilesetloader.c

@@ -9,72 +9,107 @@
 #include "assert/assert.h"
 #include "util/memory.h"
 #include "util/endian.h"
+#include "asset/loader/assetloading.h"
+#include "asset/loader/assetentry.h"
 
-errorret_t assetTilesetLoader(assetfile_t *file) {
+errorret_t assetTilesetLoaderAsync(assetloading_t *loading) {
-  assertNotNull(file, "Asset file pointer for tileset loader is null.");
+  assertNotNull(loading, "Loading cannot be NULL");
 
-  tileset_t *out = (tileset_t *)file->output;
+  if(loading->loading.tileset.state != ASSET_TILESET_LOADING_STATE_READ_FILE) {
-  assertNotNull(out, "Output pointer for tileset loader is null.");
+    errorOk();
-
-  uint8_t *entire = memoryAllocate(file->size);
-  errorChain(assetFileOpen(file));
-  errorChain(assetFileRead(file, entire, file->size));
-  errorChain(assetFileClose(file));
-  assertTrue(file->lastRead == file->size, "Failed to read entire file.");
-
-
-  if(
-    entire[0] != 'D' || 
-    entire[1] != 'T' ||
-    entire[2] != 'F'
-  ) {
-    errorThrow("Invalid tileset header");
   }
 
-  if(entire[3] != 0x00) {
+  assertNull(loading->loading.tileset.data, "Data already defined?");
-    errorThrow("Unsupported tileset version");
-  }
 
-  // Fix endianness
+  assetfile_t *file = &loading->loading.tileset.file;
+  assetLoaderErrorChain(loading, assetFileInit(file, loading->entry->name, NULL, NULL));
 
-  out->tileWidth = endianLittleToHost16(*(uint16_t *)(entire + 4));
+  uint8_t *data = memoryAllocate(file->size);
-  out->tileHeight = endianLittleToHost16(*(uint16_t *)(entire + 6));
+  assetLoaderErrorChain(loading, assetFileOpen(file));
-  out->columns = endianLittleToHost16(*(uint16_t *)(entire + 8));
+  assetLoaderErrorChain(loading, assetFileRead(file, data, file->size));
-  out->rows = endianLittleToHost16(*(uint16_t *)(entire + 10));
+  assetLoaderErrorChain(loading, assetFileClose(file));
-  // out->right = endianLittleToHost16(*(uint16_t *)(entire + 12));
+  assetLoaderErrorChain(loading, assetFileDispose(file));
-  // out->bottom = endianLittleToHost16(*(uint16_t *)(entire + 14));
+  assertTrue(file->lastRead == file->size, "Failed to read entire tileset file.");
-
-  if(out->tileWidth == 0) {
-    errorThrow("Tile width cannot be 0");
-  }
-  if(out->tileHeight == 0) {
-    errorThrow("Tile height cannot be 0");
-  }
-  if(out->columns == 0) {
-    errorThrow("Column count cannot be 0");
-  }
-  if(out->rows == 0) {
-    errorThrow("Row count cannot be 0");
-  }
-
-  out->uv[0] = endianLittleToHostFloat(*(float *)(entire + 16));
-  out->uv[1] = endianLittleToHostFloat(*(float *)(entire + 20));
-
-  if(out->uv[1] < 0.0f || out->uv[1] > 1.0f) {
-    errorThrow("Invalid v0 value in tileset");
-  }
-
-  // Setup tileset
-  out->tileCount = out->columns * out->rows;
-
-  memoryFree(entire);
 
+  loading->loading.tileset.data = data;
+  loading->loading.tileset.state = ASSET_TILESET_LOADING_STATE_PARSE;
+  loading->entry->state = ASSET_ENTRY_STATE_PENDING_SYNC;
   errorOk();
 }
 
-errorret_t assetTilesetLoad(
+errorret_t assetTilesetLoaderSync(assetloading_t *loading) {
-  const char_t *path,
+  assertNotNull(loading, "Loading cannot be NULL");
-  tileset_t *out
+  assertTrue(loading->type == ASSET_LOADER_TYPE_TILESET, "Invalid type.");
-) {
+
-  return assetLoad(path, assetTilesetLoader, NULL, out);
+  switch(loading->loading.tileset.state) {
+    case ASSET_TILESET_LOADING_STATE_INITIAL:
+      loading->loading.tileset.state = ASSET_TILESET_LOADING_STATE_READ_FILE;
+      loading->entry->state = ASSET_ENTRY_STATE_PENDING_ASYNC;
+      errorOk();
+      break;
+
+    case ASSET_TILESET_LOADING_STATE_PARSE:
+      break;
+
+    default:
+      errorOk();
+  }
+
+  uint8_t *data = loading->loading.tileset.data;
+  assertNotNull(data, "Tileset data should have been loaded by now.");
+
+  tileset_t *out = &loading->entry->data.tileset;
+
+  if(data[0] != 'D' || data[1] != 'T' || data[2] != 'F') {
+    memoryFree(data);
+    assetLoaderErrorThrow(loading, "Invalid tileset header");
+  }
+
+  if(data[3] != 0x00) {
+    memoryFree(data);
+    assetLoaderErrorThrow(loading, "Unsupported tileset version");
+  }
+
+  out->tileWidth = endianLittleToHost16(*(uint16_t *)(data + 4));
+  out->tileHeight = endianLittleToHost16(*(uint16_t *)(data + 6));
+  out->columns = endianLittleToHost16(*(uint16_t *)(data + 8));
+  out->rows = endianLittleToHost16(*(uint16_t *)(data + 10));
+
+  if(out->tileWidth == 0) {
+    memoryFree(data);
+    assetLoaderErrorThrow(loading, "Tile width cannot be 0");
+  }
+  if(out->tileHeight == 0) {
+    memoryFree(data);
+    assetLoaderErrorThrow(loading, "Tile height cannot be 0");
+  }
+  if(out->columns == 0) {
+    memoryFree(data);
+    assetLoaderErrorThrow(loading, "Column count cannot be 0");
+  }
+  if(out->rows == 0) {
+    memoryFree(data);
+    assetLoaderErrorThrow(loading, "Row count cannot be 0");
+  }
+
+  out->uv[0] = endianLittleToHostFloat(*(float *)(data + 16));
+  out->uv[1] = endianLittleToHostFloat(*(float *)(data + 20));
+
+  if(out->uv[1] < 0.0f || out->uv[1] > 1.0f) {
+    memoryFree(data);
+    assetLoaderErrorThrow(loading, "Invalid v0 value in tileset");
+  }
+
+  out->tileCount = out->columns * out->rows;
+  memoryFree(data);
+  loading->loading.tileset.data = NULL;
+
+  loading->entry->state = ASSET_ENTRY_STATE_LOADED;
+  errorOk();
+}
+
+errorret_t assetTilesetDispose(assetentry_t *entry) {
+  assertNotNull(entry, "Entry cannot be NULL");
+  assertTrue(entry->type == ASSET_LOADER_TYPE_TILESET, "Invalid type.");
+  errorOk();
 }

src/dusk/asset/loader/display/assettilesetloader.h

@@ -6,25 +6,55 @@
  */
 
 #pragma once
-#include "asset/asset.h"
+#include "asset/assetfile.h"
 #include "display/texture/tileset.h"
 
-/**
+typedef struct assetloading_s assetloading_t;
- * Handler for tileset assets.
+typedef struct assetentry_s assetentry_t;
- * 
+
- * @param file Asset file to load the tileset from.
+typedef struct {
- * @return Any error that occurs during loading.
+  void *nothing;
- */
+} assettilesetloaderinput_t;
-errorret_t assetTilesetLoader(assetfile_t *file);
+
+typedef enum {
+  ASSET_TILESET_LOADING_STATE_INITIAL,
+  ASSET_TILESET_LOADING_STATE_READ_FILE,
+  ASSET_TILESET_LOADING_STATE_PARSE,
+  ASSET_TILESET_LOADING_STATE_DONE
+} assettilesetloadingstate_t;
+
+typedef struct {
+  assetfile_t file;
+  assettilesetloadingstate_t state;
+
+  uint8_t *data;
+} assettilesetloaderloading_t;
+
+typedef tileset_t assettilesetoutput_t;
 
 /**
- * Loads a tileset from the specified path.
+ * Asynchronous loader for tileset assets. Reads the raw DTF file bytes into
+ * the loading buffer so the sync phase can parse without blocking the main
+ * thread on I/O.
  *
- * @param path Path to the tileset asset.
+ * @param loading Loading information for the asset being loaded.
- * @param out Output tileset to load into.
+ * @return Error code indicating success or failure of the load operation.
- * @return Any error that occurs during loading.
  */
-errorret_t assetTilesetLoad(
+errorret_t assetTilesetLoaderAsync(assetloading_t *loading);
-  const char_t *path,
+
-  tileset_t *out
+/**
-);
+ * Synchronous loader for tileset assets. Parses the DTF binary previously
+ * read by the async phase and populates the output tileset_t.
+ *
+ * @param loading Loading information for the asset being loaded.
+ * @return Error code indicating success or failure of the load operation.
+ */
+errorret_t assetTilesetLoaderSync(assetloading_t *loading);
+
+/**
+ * Disposer for tileset assets.
+ *
+ * @param entry Asset entry containing the tileset to dispose.
+ * @return Error code indicating success or failure of the dispose operation.
+ */
+errorret_t assetTilesetDispose(assetentry_t *entry);

src/dusk/asset/loader/json/assetjsonloader.c

@@ -8,46 +8,81 @@
 #include "assetjsonloader.h"
 #include "util/memory.h"
 #include "assert/assert.h"
+#include "asset/loader/assetloading.h"
+#include "asset/loader/assetentry.h"
 
-errorret_t assetJsonLoadFileToDoc(assetfile_t *file, yyjson_doc **outDoc) {
+errorret_t assetJsonLoaderAsync(assetloading_t *loading) {
-  assertNotNull(file, "Asset file pointer for JSON loader is null.");
+  assertNotNull(loading, "Loading cannot be NULL");
-  assertNotNull(outDoc, "Output pointer for JSON loader is null.");
 
-  if(file->size > ASSET_JSON_FILE_SIZE_MAX) {
+  if(loading->loading.json.state != ASSET_JSON_LOADING_STATE_READ_FILE) {
-    errorThrow("JSON exceeds maximum allowed size");
+    errorOk();
   }
 
-  // Create buffer
+  assertNull(loading->loading.json.buffer, "Buffer already defined?");
-  uint8_t *buffer = memoryAllocate(file->size);
 
-  errorChain(assetFileOpen(file));
+  assetfile_t *file = &loading->loading.json.file;
+  assetLoaderErrorChain(loading, assetFileInit(file, loading->entry->name, NULL, NULL));
 
-  // Read entire file
+  if(file->size > ASSET_JSON_FILE_SIZE_MAX) {
-  errorChain(assetFileRead(file, buffer, file->size));
+    assetLoaderErrorThrow(loading, "JSON exceeds maximum allowed size");
+  }
+
+  size_t fileSize = (size_t)file->size;
+  uint8_t *buffer = memoryAllocate(fileSize);
+  assetLoaderErrorChain(loading, assetFileOpen(file));
+  assetLoaderErrorChain(loading, assetFileRead(file, buffer, fileSize));
   assertTrue(file->lastRead == file->size, "Failed to read entire JSON file.");
+  assetLoaderErrorChain(loading, assetFileClose(file));
+  assetLoaderErrorChain(loading, assetFileDispose(file));
 
-  errorChain(assetFileClose(file));
+  loading->loading.json.buffer = buffer;
-
+  loading->loading.json.size = fileSize;
-  *outDoc = yyjson_read(
+  loading->loading.json.state = ASSET_JSON_LOADING_STATE_PARSE;
-    buffer,
+  loading->entry->state = ASSET_ENTRY_STATE_PENDING_SYNC;
-    file->size,
-    YYJSON_READ_ALLOW_COMMENTS | YYJSON_READ_ALLOW_TRAILING_COMMAS
-  );
-  memoryFree(buffer);
-
-  if(!*outDoc) errorThrow("Failed to parse JSON");
   errorOk();
 }
 
-errorret_t assetJsonLoader(assetfile_t *file) {
+errorret_t assetJsonLoaderSync(assetloading_t *loading) {
-  yyjson_doc **outDoc = (yyjson_doc **)file->output;
+  assertNotNull(loading, "Loading cannot be NULL");
-  assertNotNull(outDoc, "Output pointer for JSON loader is null.");
+  assertTrue(loading->type == ASSET_LOADER_TYPE_JSON, "Invalid type.");
-  return assetJsonLoadFileToDoc(file, outDoc);
+
+  switch(loading->loading.json.state) {
+    case ASSET_JSON_LOADING_STATE_INITIAL:
+      loading->loading.json.state = ASSET_JSON_LOADING_STATE_READ_FILE;
+      loading->entry->state = ASSET_ENTRY_STATE_PENDING_ASYNC;
+      errorOk();
+      break;
+
+    case ASSET_JSON_LOADING_STATE_PARSE:
+      break;
+
+    default:
+      errorOk();
+  }
+
+  uint8_t *buffer = loading->loading.json.buffer;
+  assertNotNull(buffer, "JSON buffer should have been loaded by now.");
+
+  loading->entry->data.json = yyjson_read(
+    (char *)buffer,
+    loading->loading.json.size,
+    YYJSON_READ_ALLOW_COMMENTS | YYJSON_READ_ALLOW_TRAILING_COMMAS
+  );
+  memoryFree(buffer);
+  loading->loading.json.buffer = NULL;
+
+  if(!loading->entry->data.json) {
+    assetLoaderErrorThrow(loading, "Failed to parse JSON");
+  }
+
+  loading->entry->state = ASSET_ENTRY_STATE_LOADED;
+  errorOk();
 }
 
-errorret_t assetJsonLoad(
+errorret_t assetJsonDispose(assetentry_t *entry) {
-  const char_t *path,
+  assertNotNull(entry, "Asset entry cannot be NULL");
-  yyjson_doc **outDoc
+  assertTrue(entry->type == ASSET_LOADER_TYPE_JSON, "Invalid type.");
-) {
+  yyjson_doc_free(entry->data.json);
-  return assetLoad(path, assetJsonLoader, NULL, outDoc);
+  entry->data.json = NULL;
+  errorOk();
 }

src/dusk/asset/loader/json/assetjsonloader.h

@@ -6,40 +6,32 @@
  */
 
 #pragma once
-#include "asset/asset.h"
+#include "asset/assetfile.h"
 #include "yyjson.h"
 
 #define ASSET_JSON_FILE_SIZE_MAX 1024*256
 
+typedef struct assetloading_s assetloading_t;
+typedef struct assetentry_s assetentry_t;
+
+typedef struct { void *nothing; } assetjsonloaderinput_t;
+
+typedef enum {
+  ASSET_JSON_LOADING_STATE_INITIAL,
+  ASSET_JSON_LOADING_STATE_READ_FILE,
+  ASSET_JSON_LOADING_STATE_PARSE,
+  ASSET_JSON_LOADING_STATE_DONE
+} assetjsonloadingstate_t;
+
 typedef struct {
-  void *nothing;
+  assetfile_t file;
-} assetjsonloaderparams_t;
+  assetjsonloadingstate_t state;
+  uint8_t *buffer;
+  size_t size;
+} assetjsonloaderloading_t;
 
-/**
+typedef yyjson_doc * assetjsonoutput_t;
- * Loads a JSON document from the specified asset file.
- * 
- * @param file Asset file to load the JSON document from.
- * @param outDoc Pointer to store the loaded JSON document.
- * @return Any error that occurs during loading.
- */
-errorret_t assetJsonLoadFileToDoc(assetfile_t *file, yyjson_doc **outDoc);
 
-/**
+errorret_t assetJsonLoaderAsync(assetloading_t *loading);
- * Handler for locale assets.
+errorret_t assetJsonLoaderSync(assetloading_t *loading);
- * 
+errorret_t assetJsonDispose(assetentry_t *entry);
- * @param file Asset file to load the locale from.
- * @return Any error that occurs during loading.
- */
-errorret_t assetJsonLoader(assetfile_t *file);
-
-/**
- * Loads a locale from the specified path.
- * 
- * @param path Path to the locale asset.
- * @param outDoc Pointer to store the loaded JSON document.
- * @return Any error that occurs during loading.
- */
-errorret_t assetJsonLoad(
-  const char_t *path,
-  yyjson_doc **outDoc
-);

src/dusk/asset/loader/locale/assetlocaleloader.c

@@ -11,38 +11,60 @@
 #include "util/string.h"
 #include "assert/assert.h"
 
-errorret_t assetLocaleFileInit(
+#include "asset/loader/assetloading.h"
-  assetlocalefile_t *localeFile,
+#include "asset/loader/assetentry.h"
-  const char_t *path
-) {
-  assertNotNull(localeFile, "Locale file cannot be NULL.");
-  assertNotNull(path, "Locale file path cannot be NULL.");
 
+errorret_t assetLocaleLoaderAsync(assetloading_t *loading) {
+  assertNotNull(loading, "Loading cannot be NULL");
+
+  if(loading->loading.locale.state != ASSET_LOCALE_LOADER_STATE_LOAD_HEADER) {
+    errorOk();
+  }
+
+  assetlocalefile_t *localeFile = &loading->entry->data.locale;
   memoryZero(localeFile, sizeof(assetlocalefile_t));
+  assetLoaderErrorChain(loading, assetFileInit(&localeFile->file, loading->entry->name, NULL, NULL));
+  assetLoaderErrorChain(loading, assetFileOpen(&localeFile->file));
 
-  // Init the asset file.
-  errorChain(assetFileInit(&localeFile->file, path, NULL, NULL));
-
-  // Open the file handle
-  errorChain(assetFileOpen(&localeFile->file));
-
-  // Get the blank key, this is basically the header info for po files
   char_t buffer[1024];
-  errorChain(assetLocaleGetString(localeFile, "", 0, buffer, sizeof(buffer)));
+  assetLoaderErrorChain(loading, assetLocaleGetString(localeFile, "", 0, buffer, sizeof(buffer)));
-  errorChain(assetLocaleParseHeader(localeFile, buffer, sizeof(buffer)));
+  assetLoaderErrorChain(loading, assetLocaleParseHeader(localeFile, buffer, sizeof(buffer)));
 
+  loading->loading.locale.state = ASSET_LOCALE_LOADER_STATE_DONE;
+  loading->entry->state = ASSET_ENTRY_STATE_PENDING_SYNC;
   errorOk();
 }
 
-errorret_t assetLocaleFileDispose(assetlocalefile_t *localeFile) {
+errorret_t assetLocaleLoaderSync(assetloading_t *loading) {
-  assertNotNull(localeFile, "Locale file cannot be NULL.");
+  assertNotNull(loading, "Loading cannot be NULL");
+  assertTrue(loading->type == ASSET_LOADER_TYPE_LOCALE, "Invalid type.");
 
-  errorChain(assetFileClose(&localeFile->file));
+  switch(loading->loading.locale.state) {
-  errorChain(assetFileDispose(&localeFile->file));
+    case ASSET_LOCALE_LOADER_STATE_INITIAL:
+      loading->loading.locale.state = ASSET_LOCALE_LOADER_STATE_LOAD_HEADER;
+      loading->entry->state = ASSET_ENTRY_STATE_PENDING_ASYNC;
+      errorOk();
+      break;
 
+    case ASSET_LOCALE_LOADER_STATE_DONE:
+      break;
+
+    default:
+      errorOk();
+  }
+
+  loading->entry->state = ASSET_ENTRY_STATE_LOADED;
   errorOk();
 }
 
+errorret_t assetLocaleDispose(assetentry_t *entry) {
+  assertNotNull(entry, "Asset entry cannot be NULL");
+  assertTrue(entry->type == ASSET_LOADER_TYPE_LOCALE, "Invalid type.");
+  assetlocalefile_t *localeFile = &entry->data.locale;
+  errorChain(assetFileClose(&localeFile->file));
+  return assetFileDispose(&localeFile->file);
+}
+
 errorret_t assetLocaleParseHeader(
   assetlocalefile_t *localeFile,
   char_t *headerBuffer,
@@ -307,13 +329,21 @@ errorret_t assetLocaleLineSkipBlanks(
   while(!reader->eof) {
     // Skip blank lines
     if(lineBuffer[0] == '\0') {
-      errorChain(assetFileLineReaderNext(reader));
+      errorret_t r = assetFileLineReaderNext(reader);
+      if(errorIsNotOk(r)) {
+        errorCatch(r);
+        break;
+      }
       continue;
     }
 
     // Skip comment lines
     if(lineBuffer[0] == '#') {
-      errorChain(assetFileLineReaderNext(reader));
+      errorret_t r = assetFileLineReaderNext(reader);
+      if(errorIsNotOk(r)) {
+        errorCatch(r);
+        break;
+      }
       continue;
     }
 
@@ -329,7 +359,11 @@ errorret_t assetLocaleLineSkipBlanks(
     }
 
     if(onlySpaces) {
-      errorChain(assetFileLineReaderNext(reader));
+      errorret_t r = assetFileLineReaderNext(reader);
+      if(errorIsNotOk(r)) {
+        errorCatch(r);
+        break;
+      }
       continue;
     }
     break;
@@ -365,10 +399,18 @@ errorret_t assetLocaleLineUnbuffer(
 
   // Now start buffering lines out
   while(!reader->eof) {
-    errorChain(assetFileLineReaderNext(reader));
+    errorret_t r = assetFileLineReaderNext(reader);
+    if(errorIsNotOk(r)) {
+      errorCatch(r);
+      break;
+    }
 
     // Skip blank lines
-    errorChain(assetLocaleLineSkipBlanks(reader, lineBuffer));
+    r = assetLocaleLineSkipBlanks(reader, lineBuffer);
+    if(errorIsNotOk(r)) {
+      errorCatch(r);
+      break;
+    }
     
     // Skip starting spaces
     char_t *ptr = (char_t *)lineBuffer;
@@ -593,7 +635,7 @@ errorret_t assetLocaleGetStringWithVA(
     tempBuffer,
     bufferSize
   );
-  if(ret.code != ERROR_OK) {
+  if(errorIsNotOk(ret)) {
     memoryFree(tempBuffer);
     return ret;
   }
@@ -641,7 +683,7 @@ errorret_t assetLocaleGetStringWithArgs(
     format,
     bufferSize
   );
-  if(ret.code != ERROR_OK) {
+  if(errorIsNotOk(ret)) {
     memoryFree(format);
     return ret;
   }

src/dusk/asset/loader/locale/assetlocaleloader.h

@@ -6,10 +6,35 @@
  */
 
 #pragma once
-#include "asset/asset.h"
+#include "asset/assetfile.h"
 
+typedef struct assetloading_s assetloading_t;
+typedef struct assetentry_s assetentry_t;
+
+/** Input passed to the locale loader — currently unused. */
+typedef struct { void *nothing; } assetlocaleloaderinput_t;
+
+typedef enum {
+  ASSET_LOCALE_LOADER_STATE_INITIAL,
+  ASSET_LOCALE_LOADER_STATE_LOAD_HEADER,
+  ASSET_LOCALE_LOADER_STATE_DONE
+} assetlocaleloaderstate_t;
+
+/** Per-slot scratch data used while the locale file is loading. */
+typedef struct {
+  assetlocaleloaderstate_t state;
+} assetlocaleloaderloading_t;
+
+/** Maximum number of distinct plural forms a locale file may declare. */
 #define ASSET_LOCALE_FILE_PLURAL_FORM_COUNT 6
 
+/**
+ * Comparison operator used in a plural-form expression.
+ *
+ * Each condition in the plural-form header is evaluated as
+ *   `n <op> value`
+ * where `n` is the runtime plural count.
+ */
 typedef enum {
   ASSET_LOCALE_PLURAL_OP_EQUAL,
   ASSET_LOCALE_PLURAL_OP_NOT_EQUAL,
@@ -19,13 +44,24 @@ typedef enum {
   ASSET_LOCALE_PLURAL_OP_GREATER_EQUAL
 } assetlocalepluraloperation_t;
 
+/**
+ * Discriminator tag for a locale string argument.
+ * @see assetlocalearg_t
+ */
 typedef enum {
   ASSET_LOCALE_ARG_STRING,
   ASSET_LOCALE_ARG_INT,
   ASSET_LOCALE_ARG_FLOAT
 } assetlocaleargtype_t;
 
+/**
+ * A single typed argument for locale string substitution.
+ *
+ * Used with @ref assetLocaleGetStringWithArgs to fill `%s`, `%d`, or `%f`
+ * placeholders inside a translated string.
+ */
 typedef struct {
+  /** Which union member is active. */
   assetlocaleargtype_t type;
   union {
     const char_t *stringValue;
@@ -34,35 +70,81 @@ typedef struct {
   };
 } assetlocalearg_t;
 
+/**
+ * Runtime state for an open locale file.
+ *
+ * Loaded once by @ref assetLocaleLoaderSync and kept alive for the lifetime
+ * of the asset entry. The plural-form fields are populated from the PO header
+ * by @ref assetLocaleParseHeader.
+ *
+ * Plural evaluation works as a linear scan over `pluralStateCount - 1`
+ * conditions; if none match, `pluralDefaultIndex` is returned.
+ */
 typedef struct {
+  /** Underlying file handle used to rewind and re-read the PO data. */
   assetfile_t file;
+
+  /** Comparison operator for each conditional plural clause. */
   assetlocalepluraloperation_t pluralOps[ASSET_LOCALE_FILE_PLURAL_FORM_COUNT];
+
+  /** Right-hand value for each conditional plural clause. */
   int32_t pluralValues[ASSET_LOCALE_FILE_PLURAL_FORM_COUNT];
+
+  /** Form index returned when the corresponding condition is true. */
   int32_t pluralIndices[ASSET_LOCALE_FILE_PLURAL_FORM_COUNT];
+
+  /** Total number of plural forms declared by `nplurals=`. */
   uint8_t pluralStateCount;
+
+  /** Form index used when no conditional clause matches. */
   uint8_t pluralDefaultIndex;
 } assetlocalefile_t;
 
-/**
+/** Convenience alias — the loaded output type of a locale asset entry. */
- * Initialize a locale asset file.
+typedef assetlocalefile_t assetlocaleoutput_t;
- * 
- * @param localeFile The locale file to initialize.
- * @param path The path to the locale file.
- * @return An error code if a failure occurs.
- */
-errorret_t assetLocaleFileInit(
-  assetlocalefile_t *localeFile,
-  const char_t *path
-);
 
 /**
- * Dispose of a locale asset file.
+ * Asynchronous loader callback. Opens the locale file, reads the PO header,
+ * and parses plural-form rules. All I/O happens here so the main thread is
+ * not blocked. Sets entry state to `ASSET_ENTRY_STATE_PENDING_SYNC` on
+ * success or `ASSET_ENTRY_STATE_ERROR` on failure.
  *
- * @param localeFile The locale file to dispose of.
+ * @param loading The loading slot for this asset entry.
- * @return An error code if a failure occurs.
+ * @return OK on success, error otherwise.
  */
-errorret_t assetLocaleFileDispose(assetlocalefile_t *localeFile);
+errorret_t assetLocaleLoaderAsync(assetloading_t *loading);
 
+/**
+ * Synchronous loader callback. Confirms the async phase completed and marks
+ * the entry as `ASSET_ENTRY_STATE_LOADED`.
+ *
+ * @param loading The loading slot for this asset entry.
+ * @return OK on success, error otherwise.
+ */
+errorret_t assetLocaleLoaderSync(assetloading_t *loading);
+
+/**
+ * Dispose callback. Closes the open file handle and zeros the locale data.
+ *
+ * @param entry The asset entry to dispose.
+ * @return OK on success, error otherwise.
+ */
+errorret_t assetLocaleDispose(assetentry_t *entry);
+
+/**
+ * Parses the `Plural-Forms:` line from a PO header string and populates the
+ * plural-form fields of `localeFile`. If no `Plural-Forms:` key is present
+ * the function returns OK without modifying the struct.
+ *
+ * Supports the `nplurals=N; plural=(<expr>);` syntax where `<expr>` is a
+ * chain of `n <op> value ? index : ...` ternary conditions ending with a
+ * fallback index.
+ *
+ * @param localeFile  Struct whose plural fields will be filled in.
+ * @param headerBuffer  The raw PO header string (msgstr of msgid "").
+ * @param headerBufferSize  Size of `headerBuffer` in bytes.
+ * @return OK on success, error if the plural expression is malformed.
+ */
 errorret_t assetLocaleParseHeader(
   assetlocalefile_t *localeFile,
   char_t *headerBuffer,
@@ -70,11 +152,29 @@ errorret_t assetLocaleParseHeader(
 );
 
 /**
- * Skips blank lines and comment lines in the line reader.
+ * Evaluates which plural form index to use for a given count.
  *
- * @param reader Line reader to read from.
+ * Walks the conditions stored in `file` in order; returns the index for the
- * @param lineBuffer Buffer to use for reading lines.
+ * first condition that matches `pluralCount`. Falls back to
- * @return Any error that occurs during skipping.
+ * `file->pluralDefaultIndex` if none match.
+ *
+ * @param file  Locale file with parsed plural rules.
+ * @param pluralCount  The runtime count (e.g. number of items).
+ * @return Zero-based plural form index.
+ */
+uint8_t assetLocaleEvaluatePlural(
+  assetlocalefile_t *file,
+  const int32_t pluralCount
+);
+
+/**
+ * Advances the line reader past blank lines, comment lines (starting with
+ * `#`), and lines containing only spaces. Stops at the first content line or
+ * end of file.
+ *
+ * @param reader  Line reader positioned at the current line.
+ * @param lineBuffer  Output buffer that the reader writes each line into.
+ * @return OK on success, error if reading fails.
  */
 errorret_t assetLocaleLineSkipBlanks(
   assetfilelinereader_t *reader,
@@ -82,16 +182,19 @@ errorret_t assetLocaleLineSkipBlanks(
 );
 
 /**
- * Unbuffers a potentially multi-line quoted string from the line reader.
+ * Reads a PO quoted string value from the current line and any immediately
+ * following continuation lines that begin with `"`.
  *
- * This will read lines until it finds a line that starts with a quote, then
+ * Handles standard C escape sequences (`\n`, `\t`, `\\`, `\"`).
- * read until the closing quote.
  *
- * @param reader Line reader to read from.
+ * @param reader  Line reader positioned at the line containing the opening
- * @param lineBuffer Buffer to use for reading lines.
+ *                quote (e.g. `msgstr "..."`).
- * @param stringBuffer Buffer to write the unbuffered string to.
+ * @param lineBuffer  Buffer the reader fills on each @ref assetFileLineReaderNext
- * @param stringBufferSize Size of the string buffer.
+ *                    call; also used to detect continuation lines.
- * @return Any error that occurs during unbuffering.
+ * @param stringBuffer  Destination for the unescaped string content.
+ * @param stringBufferSize  Capacity of `stringBuffer` in bytes.
+ * @return OK on success, error if a quote or escape sequence is malformed or
+ *         the buffer would overflow.
  */
 errorret_t assetLocaleLineUnbuffer(
   assetfilelinereader_t *reader,
@@ -101,14 +204,19 @@ errorret_t assetLocaleLineUnbuffer(
 );
 
 /**
- * Test function for locale asset loading.
+ * Looks up a translated string by message ID from the open locale file.
  *
- * @param file Asset file to test loading from.
+ * Rewinds the file and scans from the beginning on every call. For plural
- * @param messageId The message ID to retrieve.
+ * entries (`msgid_plural`) the `pluralCount` is evaluated against the loaded
- * @param pluralCount Count for formulating the plural variant.
+ * plural rules to select the correct `msgstr[N]` form.
- * @param stringBuffer Buffer to write the retrieved string to.
+ *
- * @param stringBufferSize Size of the string buffer.
+ * @param file  Locale file to search. Must be open.
- * @return Any error that occurs during testing.
+ * @param messageId  PO message ID to find (`""` retrieves the header entry).
+ * @param pluralCount  Count used to select the plural form (ignored for
+ *                     singular entries).
+ * @param stringBuffer  Buffer to receive the translated string.
+ * @param stringBufferSize  Capacity of `stringBuffer` in bytes.
+ * @return OK on success, error if the message ID is not found or I/O fails.
  */
 errorret_t assetLocaleGetString(
   assetlocalefile_t *file,
@@ -119,15 +227,21 @@ errorret_t assetLocaleGetString(
 );
 
 /**
- * Test function for locale asset loading with a variable argument list.
+ * Looks up a translated string and formats it with a `printf`-style variadic
+ * argument list.
  *
- * @param file Asset file to test loading from.
+ * Retrieves the raw format string via @ref assetLocaleGetString then applies
- * @param messageId The message ID to retrieve.
+ * `vsnprintf` with the provided arguments.
- * @param pluralCount Count for formulating the plural variant.
+ *
- * @param buffer Buffer to write the retrieved string to.
+ * @param file  Locale file to search. Must be open.
- * @param bufferSize Size of the buffer.
+ * @param messageId  PO message ID to find.
- * @param ... Additional arguments for formatting the string.
+ * @param pluralCount  Count used to select the plural form.
- * @return Any error that occurs during testing.
+ * @param buffer  Buffer to receive the formatted string.
+ * @param bufferSize  Capacity of `buffer` in bytes.
+ * @param ...  Format arguments matching the specifiers in the translated
+ *             string.
+ * @return OK on success, error if the message is not found or formatting
+ *         fails.
  */
 errorret_t assetLocaleGetStringWithVA(
   assetlocalefile_t *file,
@@ -139,16 +253,22 @@ errorret_t assetLocaleGetStringWithVA(
 );
 
 /**
- * Test function for locale asset loading with a list of arguments.
+ * Looks up a translated string and substitutes typed arguments into its
+ * `%s`, `%d`, and `%f` placeholders.
  *
- * @param file Asset file to test loading from.
+ * Unlike @ref assetLocaleGetStringWithVA this variant accepts an explicit
- * @param messageId The message ID to retrieve.
+ * array of @ref assetlocalearg_t values, which is safer to use from
- * @param pluralCount Count for formulating the plural variant.
+ * generated or scripted call sites.
- * @param buffer Buffer to write the retrieved string to.
+ *
- * @param bufferSize Size of the buffer.
+ * @param file  Locale file to search. Must be open.
- * @param args List of arguments for formatting the string.
+ * @param messageId  PO message ID to find.
- * @param argCount Number of arguments in the list.
+ * @param pluralCount  Count used to select the plural form.
- * @return Any error that occurs during testing.
+ * @param buffer  Buffer to receive the formatted string.
+ * @param bufferSize  Capacity of `buffer` in bytes.
+ * @param args  Array of typed arguments; may be NULL when `argCount` is 0.
+ * @param argCount  Number of elements in `args`.
+ * @return OK on success, error if the message is not found, an argument type
+ *         mismatches the specifier, or the buffer would overflow.
  */
 errorret_t assetLocaleGetStringWithArgs(
   assetlocalefile_t *file,

src/dusk/asset/loader/script/CMakeLists.txt

@@ -0,0 +1,9 @@
+# Copyright (c) 2026 Dominic Masters
+#
+# This software is released under the MIT License.
+# https://opensource.org/licenses/MIT
+
+target_sources(${DUSK_LIBRARY_TARGET_NAME}
+  PUBLIC
+    assetscriptloader.c
+)

src/dusk/asset/loader/script/assetscriptloader.c

@@ -0,0 +1,116 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#include "assetscriptloader.h"
+#include "asset/loader/assetloading.h"
+#include "asset/loader/assetentry.h"
+#include "asset/loader/assetloader.h"
+#include "util/memory.h"
+#include "assert/assert.h"
+#include <jerryscript.h>
+
+errorret_t assetScriptLoaderAsync(assetloading_t *loading) {
+  assertNotNull(loading, "Loading cannot be NULL");
+
+  if(loading->loading.script.state != ASSET_SCRIPT_LOADING_STATE_READ_FILE) {
+    errorOk();
+  }
+
+  assertNull(loading->loading.script.buffer, "Buffer already defined?");
+
+  assetfile_t *file = &loading->loading.script.file;
+  assetLoaderErrorChain(loading, assetFileInit(file, loading->entry->name, NULL, NULL));
+  assetLoaderErrorChain(loading, assetFileOpen(file));
+
+  size_t capacity = ASSET_SCRIPT_CHUNK_SIZE;
+  uint8_t *buffer = memoryAllocate(capacity + 1);
+  size_t offset = 0;
+
+  while(1) {
+    if(offset + ASSET_SCRIPT_CHUNK_SIZE > capacity) {
+      size_t oldCapacity = capacity + 1;
+      capacity += ASSET_SCRIPT_CHUNK_SIZE;
+      memoryResize((void **)&buffer, oldCapacity, capacity + 1);
+    }
+    assetLoaderErrorChain(loading, assetFileRead(
+      file, buffer + offset, ASSET_SCRIPT_CHUNK_SIZE
+    ));
+    size_t chunk = (size_t)file->lastRead;
+    offset += chunk;
+    if(chunk == 0) break;
+  }
+
+  buffer[offset] = '\0';
+  assetLoaderErrorChain(loading, assetFileClose(file));
+  assetLoaderErrorChain(loading, assetFileDispose(file));
+
+  loading->loading.script.buffer = buffer;
+  loading->loading.script.size = offset;
+  loading->loading.script.state = ASSET_SCRIPT_LOADING_STATE_EXEC;
+  loading->entry->state = ASSET_ENTRY_STATE_PENDING_SYNC;
+  errorOk();
+}
+
+errorret_t assetScriptLoaderSync(assetloading_t *loading) {
+  assertNotNull(loading, "Loading cannot be NULL");
+  assertTrue(loading->type == ASSET_LOADER_TYPE_SCRIPT, "Invalid type.");
+
+  switch(loading->loading.script.state) {
+    case ASSET_SCRIPT_LOADING_STATE_INITIAL:
+      loading->loading.script.state = ASSET_SCRIPT_LOADING_STATE_READ_FILE;
+      loading->entry->state = ASSET_ENTRY_STATE_PENDING_ASYNC;
+      errorOk();
+      break;
+
+    case ASSET_SCRIPT_LOADING_STATE_EXEC:
+      break;
+
+    default:
+      errorOk();
+  }
+
+  uint8_t *buffer = loading->loading.script.buffer;
+  assertNotNull(buffer, "Script buffer should have been loaded by now.");
+
+  jerry_value_t result = jerry_eval(
+    (const jerry_char_t *)buffer,
+    loading->loading.script.size,
+    JERRY_PARSE_NO_OPTS
+  );
+  memoryFree(buffer);
+  loading->loading.script.buffer = NULL;
+
+  if(jerry_value_is_exception(result)) {
+    jerry_value_t errVal = jerry_exception_value(result, false);
+    jerry_value_t errStr = jerry_value_to_string(errVal);
+    char_t buf[256];
+    jerry_size_t len = jerry_string_to_buffer(
+      errStr, JERRY_ENCODING_UTF8, (jerry_char_t *)buf, sizeof(buf) - 1
+    );
+    buf[len] = '\0';
+    jerry_value_free(errStr);
+    jerry_value_free(errVal);
+    jerry_value_free(result);
+    assetLoaderErrorThrow(loading, "Script error in '%s': %s",
+      loading->entry->name, buf
+    );
+  }
+
+  loading->entry->data.script = (assetscriptoutput_t)result;
+  loading->entry->state = ASSET_ENTRY_STATE_LOADED;
+  errorOk();
+}
+
+errorret_t assetScriptDispose(assetentry_t *entry) {
+  assertNotNull(entry, "Asset entry cannot be NULL");
+  assertTrue(entry->type == ASSET_LOADER_TYPE_SCRIPT, "Invalid type.");
+  if(entry->data.script != 0) {
+    jerry_value_free((jerry_value_t)entry->data.script);
+    entry->data.script = 0;
+  }
+  errorOk();
+}

src/dusk/asset/loader/script/assetscriptloader.h

@@ -0,0 +1,35 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#pragma once
+#include "asset/assetfile.h"
+
+#define ASSET_SCRIPT_CHUNK_SIZE 1024
+
+typedef struct assetloading_s assetloading_t;
+typedef struct assetentry_s assetentry_t;
+
+typedef struct { void *nothing; } assetscriptloaderinput_t;
+typedef uint32_t assetscriptoutput_t;
+
+typedef enum {
+  ASSET_SCRIPT_LOADING_STATE_INITIAL,
+  ASSET_SCRIPT_LOADING_STATE_READ_FILE,
+  ASSET_SCRIPT_LOADING_STATE_EXEC,
+  ASSET_SCRIPT_LOADING_STATE_DONE
+} assetscriptloadingstate_t;
+
+typedef struct {
+  assetfile_t file;
+  assetscriptloadingstate_t state;
+  uint8_t *buffer;
+  size_t size;
+} assetscriptloaderloading_t;
+
+errorret_t assetScriptLoaderAsync(assetloading_t *loading);
+errorret_t assetScriptLoaderSync(assetloading_t *loading);
+errorret_t assetScriptDispose(assetentry_t *entry);

src/dusk/console/console.c

@@ -67,7 +67,7 @@ errorret_t consoleDraw(void) {
 
   for(uint32_t i = 0; i < CONSOLE_HISTORY_MAX; i++) {
     errorChain(textDraw(
-      0, FONT_DEFAULT.tileset.tileHeight * i,
+      0, FONT_DEFAULT.tileset->tileHeight * i,
       CONSOLE.line[i],
       COLOR_WHITE,
       &FONT_DEFAULT

src/dusk/display/display.c

@@ -22,7 +22,7 @@
 #include "util/memory.h"
 #include "util/string.h"
 #include "asset/asset.h"
-#include "display/shader/shaderunlit.h"
+#include "display/shader/shaderlist.h"
 #include "time/time.h"
 
 display_t DISPLAY = { 0 };
@@ -53,31 +53,8 @@ errorret_t displayInit(void) {
   errorChain(screenInit());
 
   // Setup initial shader with default values
-  mat4 view, proj, model;
-  glm_lookat(
-    (vec3){ 0.0f, 0.0f, 1.0f },
-    (vec3){ 0.0f, 0.0f, 0.0f },
-    (vec3){ 0.0f, 1.0f, 0.0f },
-    view
-  );
 
-  glm_perspective(
+  errorChain(shaderListInit());
-    glm_rad(45.0f),
-    SCREEN.aspect,
-    0.1f,
-    100.0f,
-    proj
-  );
-
-  glm_mat4_identity(model);
-
-  errorChain(shaderInit(&SHADER_UNLIT, &SHADER_UNLIT_DEFINITION));
-  errorChain(shaderBind(&SHADER_UNLIT));
-  errorChain(shaderSetMatrix(&SHADER_UNLIT, SHADER_UNLIT_PROJECTION, proj));
-  errorChain(shaderSetMatrix(&SHADER_UNLIT, SHADER_UNLIT_VIEW, view));
-  errorChain(shaderSetMatrix(&SHADER_UNLIT, SHADER_UNLIT_MODEL, model));
-  errorChain(shaderSetTexture(&SHADER_UNLIT, SHADER_UNLIT_TEXTURE, NULL));
-  errorChain(shaderSetColor(&SHADER_UNLIT, SHADER_UNLIT_COLOR, COLOR_WHITE));
 
   errorOk();
 }
@@ -119,7 +96,7 @@ errorret_t displaySetState(displaystate_t state) {
 }
 
 errorret_t displayDispose(void) {
-  errorChain(shaderDispose(&SHADER_UNLIT));
+  errorChain(shaderListDispose());
   errorChain(spriteBatchDispose());
   screenDispose();
   errorChain(textDispose());

src/dusk/display/shader/CMakeLists.txt

@@ -7,5 +7,6 @@
 target_sources(${DUSK_LIBRARY_TARGET_NAME}
   PUBLIC
     shader.c
+    shaderlist.c
     shaderunlit.c
 )

src/dusk/display/shader/shader.c

@@ -8,6 +8,7 @@
 #include "shader.h"
 #include "shadermaterial.h"
 #include "assert/assert.h"
+#include "log/log.h"
 
 shader_t *bound = NULL;
 
@@ -57,6 +58,7 @@ errorret_t shaderSetColor(
 ) {
   assertNotNull(shader, "Shader cannot be null");
   assertStrLenMin(name, 1, "Uniform name cannot be empty");
+  assertTrue(bound == shader, "Shader must be bound.");
   errorChain(shaderSetColorPlatform(shader, name, color));
   errorOk();
 }

src/dusk/display/shader/shaderlist.c

@@ -0,0 +1,87 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#include "shaderlist.h"
+#include "display/screen/screen.h"
+#include "assert/assert.h"
+
+shaderlistdef_t SHADER_LIST_DEFS[SHADER_LIST_SHADER_COUNT] = {
+  [SHADER_LIST_SHADER_UNLIT] = {
+    .shader = &SHADER_UNLIT,
+    .definition = &SHADER_UNLIT_DEFINITION
+  },
+};
+
+errorret_t shaderListInit() {
+  mat4 view, proj, model;
+  glm_lookat(
+    (vec3){ 0.0f, 0.0f, 1.0f },
+    (vec3){ 0.0f, 0.0f, 0.0f },
+    (vec3){ 0.0f, 1.0f, 0.0f },
+    view
+  );
+
+  glm_perspective(
+    glm_rad(45.0f),
+    SCREEN.aspect,
+    0.1f,
+    100.0f,
+    proj
+  );
+
+  glm_mat4_identity(model);
+
+  for(shaderlistshader_t i = 0; i < SHADER_LIST_SHADER_COUNT; i++) {
+    if(i == SHADER_LIST_SHADER_NULL) {
+      continue;
+    }
+
+    assertNotNull(
+      SHADER_LIST_DEFS[i].shader, "Shader cannot be null"
+    );
+    assertNotNull(
+      SHADER_LIST_DEFS[i].definition, "Shader definition cannot be null"
+    );
+
+    errorChain(shaderInit(
+      SHADER_LIST_DEFS[i].shader, SHADER_LIST_DEFS[i].definition
+    ));
+    errorChain(shaderBind(SHADER_LIST_DEFS[i].shader));
+    errorChain(shaderSetMatrix(
+      SHADER_LIST_DEFS[i].shader, SHADER_UNLIT_PROJECTION, proj
+    ));
+    errorChain(shaderSetMatrix(
+      SHADER_LIST_DEFS[i].shader, SHADER_UNLIT_VIEW, view
+    ));
+    errorChain(shaderSetMatrix(
+      SHADER_LIST_DEFS[i].shader, SHADER_UNLIT_MODEL, model
+    ));
+    errorChain(shaderSetTexture(
+      SHADER_LIST_DEFS[i].shader, SHADER_UNLIT_TEXTURE, NULL
+    ));
+    errorChain(shaderSetColor(
+      SHADER_LIST_DEFS[i].shader, SHADER_UNLIT_COLOR, COLOR_WHITE
+    ));
+  }
+
+  errorOk();
+}
+
+errorret_t shaderListDispose(void) {
+  for(shaderlistshader_t i = 0; i < SHADER_LIST_SHADER_COUNT; i++) {
+    if(i == SHADER_LIST_SHADER_NULL) {
+      continue;
+    }
+
+    assertNotNull(
+      SHADER_LIST_DEFS[i].shader, "Shader cannot be null"
+    );
+
+    errorChain(shaderDispose(SHADER_LIST_DEFS[i].shader));
+  }
+  errorOk();
+}

src/dusk/display/shader/shaderlist.h

@@ -0,0 +1,40 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#pragma once
+#include "display/shader/shader.h"
+#include "display/shader/shaderunlit.h"
+
+typedef enum {
+  SHADER_LIST_SHADER_NULL,
+
+  SHADER_LIST_SHADER_UNLIT,
+  
+  SHADER_LIST_SHADER_COUNT
+} shaderlistshader_t;
+
+typedef struct {
+  shader_t *shader;
+  shaderdefinition_t *definition;
+} shaderlistdef_t;
+
+extern shaderlistdef_t SHADER_LIST_DEFS[SHADER_LIST_SHADER_COUNT];
+
+/**
+ * Initializes all default shaders and uploads the initial view, projection,
+ * and model matrices to each.
+ *
+ * @return Error state.
+ */
+errorret_t shaderListInit();
+
+/**
+ * Disposes all default shaders.
+ *
+ * @return Error state.
+ */
+errorret_t shaderListDispose(void);

src/dusk/display/shader/shadermaterial.h

@@ -6,7 +6,7 @@
  */
 
 #pragma once
-#include "display/shader/shaderunlit.h"
+#include "display/shader/shaderlist.h"
 
 typedef union shadermaterial_u {
   shaderunlitmaterial_t unlit;

src/dusk/display/spritebatch/spritebatch.c

@@ -9,14 +9,13 @@
 #include "assert/assert.h"
 #include "util/memory.h"
 #include "util/math.h"
-#include "display/shader/shaderunlit.h"
+#include "display/shader/shadermaterial.h"
 
 meshvertex_t SPRITEBATCH_VERTICES[SPRITEBATCH_VERTEX_COUNT];
 spritebatch_t SPRITEBATCH;
 
 errorret_t spriteBatchInit() {
   memoryZero(&SPRITEBATCH, sizeof(spritebatch_t));
-
   errorChain(meshInit(
     &SPRITEBATCH.mesh,
     QUAD_PRIMITIVE_TYPE,
@@ -28,137 +27,100 @@ errorret_t spriteBatchInit() {
 
 errorret_t spriteBatchBuffer(
   const spritebatchsprite_t *sprites,
-  const uint32_t count
+  const uint32_t count,
+  shader_t *shader,
+  const shadermaterial_t material
 ) {
-  for(uint32_t i = 0; i < count; i++) {
+  assertNotNull(sprites, "Sprites cannot be null");
-    const spritebatchsprite_t *s = &sprites[i];
+  assertTrue(count > 0, "Count must be greater than zero");
+  assertNotNull(shader, "Shader cannot be null");
 
-    // if(s->texture != SPRITEBATCH.currentTexture) {
+  // Did the shader or material data change?
-    //   errorChain(spriteBatchFlush());
+  if(shader != SPRITEBATCH.shader) {
-    // }
+    errorChain(spriteBatchFlush());
+    SPRITEBATCH.shader = shader;
+    SPRITEBATCH.material = material;
+  } else if(memoryCompare(
+    &material, &SPRITEBATCH.material, sizeof(shadermaterial_t)
+  ) != 0) {
+    // Did the material data change?
+    errorChain(spriteBatchFlush());
+    SPRITEBATCH.shader = shader;
+    SPRITEBATCH.material = material;
+  }
 
-    if(SPRITEBATCH.spriteCount >= SPRITEBATCH_SPRITES_MAX_PER_FLUSH) {
+  // Buffer the vertices.
-      errorChain(spriteBatchFlush());
+  for(uint32_t i = 0; i < count; i++ ){
-    }
+    spritebatchsprite_t sprite = sprites[i];
 
     meshvertex_t *v = &SPRITEBATCH_VERTICES[
       (SPRITEBATCH.spriteCount + (SPRITEBATCH.spriteFlush *
       SPRITEBATCH_SPRITES_MAX_PER_FLUSH)) * QUAD_VERTEX_COUNT
     ];
     
-    v[0].pos[0] = s->min[0]; v[0].pos[1] = s->min[1]; v[0].pos[2] = s->min[2];
+    // Buffer the quad
-    v[0].uv[0] = s->uvMin[0]; v[0].uv[1] = s->uvMin[1];
+    v[0].pos[0] = sprite.min[0];
+    v[0].pos[1] = sprite.min[1];
+    v[0].pos[2] = sprite.min[2];
 
-    v[1].pos[0] = s->max[0]; v[1].pos[1] = s->min[1]; v[1].pos[2] = s->min[2];
+    v[0].uv[0] = sprite.uvMin[0];
-    v[1].uv[0] = s->uvMax[0]; v[1].uv[1] = s->uvMin[1];
+    v[0].uv[1] = sprite.uvMin[1];
 
-    v[2].pos[0] = s->max[0]; v[2].pos[1] = s->max[1]; v[2].pos[2] = s->min[2];
-    v[2].uv[0] = s->uvMax[0]; v[2].uv[1] = s->uvMax[1];
 
-    v[3].pos[0] = s->min[0]; v[3].pos[1] = s->min[1]; v[3].pos[2] = s->min[2];
+    v[1].pos[0] = sprite.max[0];
-    v[3].uv[0] = s->uvMin[0]; v[3].uv[1] = s->uvMin[1];
+    v[1].pos[1] = sprite.min[1];
+    v[1].pos[2] = sprite.min[2];
 
-    v[4].pos[0] = s->max[0]; v[4].pos[1] = s->max[1]; v[4].pos[2] = s->min[2];
+    v[1].uv[0] = sprite.uvMax[0];
-    v[4].uv[0] = s->uvMax[0]; v[4].uv[1] = s->uvMax[1];
+    v[1].uv[1] = sprite.uvMin[1];
 
-    v[5].pos[0] = s->min[0]; v[5].pos[1] = s->max[1]; v[5].pos[2] = s->min[2];
-    v[5].uv[0] = s->uvMin[0]; v[5].uv[1] = s->uvMax[1];
 
-    #if MESH_ENABLE_COLOR
+    v[2].pos[0] = sprite.max[0];
-    for(uint8_t vi = 0; vi < QUAD_VERTEX_COUNT; vi++) {
+    v[2].pos[1] = sprite.max[1];
-      v[vi].color = s->color;
+    v[2].pos[2] = sprite.max[2];
-    }
-    #endif
 
+    v[2].uv[0] = sprite.uvMax[0];
+    v[2].uv[1] = sprite.uvMax[1];
+
+
+    v[3].pos[0] = sprite.min[0];
+    v[3].pos[1] = sprite.min[1];
+    v[3].pos[2] = sprite.min[2];
+
+    v[3].uv[0] = sprite.uvMin[0];
+    v[3].uv[1] = sprite.uvMin[1];
+
+
+    v[4].pos[0] = sprite.max[0];
+    v[4].pos[1] = sprite.max[1];
+    v[4].pos[2] = sprite.max[2];
+
+    v[4].uv[0] = sprite.uvMax[0];
+    v[4].uv[1] = sprite.uvMax[1];
+
+
+    v[5].pos[0] = sprite.min[0];
+    v[5].pos[1] = sprite.max[1];
+    v[5].pos[2] = sprite.max[2];
+
+    v[5].uv[0] = sprite.uvMin[0];
+    v[5].uv[1] = sprite.uvMax[1];
+
+    // Do we need to flush?
     SPRITEBATCH.spriteCount++;
+    if(SPRITEBATCH.spriteCount >= SPRITEBATCH_SPRITES_MAX_PER_FLUSH) {
+      errorChain(spriteBatchFlush());
+    }
   }
+  
   errorOk();
 }
 
-errorret_t spriteBatchBufferSprite(const spritebatchsprite_t *sprite) {
-  return spriteBatchBuffer(sprite, 1);
-}
-
-errorret_t spriteBatchPushv(
-  const float_t *minX,
-  const float_t *minY,
-  const float_t *maxX,
-  const float_t *maxY,
-  const float_t *z,
-  #if MESH_ENABLE_COLOR
-    const color_t *color,
-  #endif
-  const float_t *u0,
-  const float_t *v0,
-  const float_t *u1,
-  const float_t *v1,
-  const size_t count
-) {
-  for(size_t i = 0; i < count; i++) {
-    spritebatchsprite_t sprite;
-    sprite.min[0] = minX[i]; sprite.min[1] = minY[i]; sprite.min[2] = z[i];
-    sprite.max[0] = maxX[i]; sprite.max[1] = maxY[i]; sprite.max[2] = z[i];
-    sprite.uvMin[0] = u0[i]; sprite.uvMin[1] = v0[i];
-    sprite.uvMax[0] = u1[i]; sprite.uvMax[1] = v1[i];
-    sprite.texture = SPRITEBATCH.currentTexture;
-    #if MESH_ENABLE_COLOR
-      sprite.color = color[i];
-    #endif
-    errorChain(spriteBatchBuffer(&sprite, 1));
-  }
-  errorOk();
-}
-
-errorret_t spriteBatchPush(
-  const float_t minX,
-  const float_t minY,
-  const float_t maxX,
-  const float_t maxY,
-  #if MESH_ENABLE_COLOR
-    const color_t color,
-  #endif
-  const float_t u0,
-  const float_t v0,
-  const float_t u1,
-  const float_t v1
-) {
-  spritebatchsprite_t sprite;
-  sprite.min[0] = minX; sprite.min[1] = minY; sprite.min[2] = 0;
-  sprite.max[0] = maxX; sprite.max[1] = maxY; sprite.max[2] = 0;
-  sprite.uvMin[0] = u0; sprite.uvMin[1] = v0;
-  sprite.uvMax[0] = u1; sprite.uvMax[1] = v1;
-  sprite.texture = SPRITEBATCH.currentTexture;
-  #if MESH_ENABLE_COLOR
-    sprite.color = color;
-  #endif
-  return spriteBatchBuffer(&sprite, 1);
-}
-
-errorret_t spriteBatchPushZ(
-  const vec3 min,
-  const vec3 max,
-  #if MESH_ENABLE_COLOR
-    const color_t color,
-  #endif
-  const vec2 uvMin,
-  const vec2 uvMax
-) {
-  spritebatchsprite_t sprite;
-  sprite.min[0] = min[0]; sprite.min[1] = min[1]; sprite.min[2] = min[2];
-  sprite.max[0] = max[0]; sprite.max[1] = max[1]; sprite.max[2] = max[2];
-  sprite.uvMin[0] = uvMin[0]; sprite.uvMin[1] = uvMin[1];
-  sprite.uvMax[0] = uvMax[0]; sprite.uvMax[1] = uvMax[1];
-  sprite.texture = SPRITEBATCH.currentTexture;
-  #if MESH_ENABLE_COLOR
-    sprite.color = color;
-  #endif
-  return spriteBatchBuffer(&sprite, 1);
-}
-
 void spriteBatchClear() {
   SPRITEBATCH.spriteCount = 0;
   SPRITEBATCH.spriteFlush = 0;
-  SPRITEBATCH.currentTexture = NULL;
+  SPRITEBATCH.shader = NULL;
+  memoryZero(&SPRITEBATCH.material, sizeof(shadermaterial_t));
 }
 
 errorret_t spriteBatchFlush() {
@@ -171,6 +133,9 @@ errorret_t spriteBatchFlush() {
     SPRITEBATCH.spriteFlush * SPRITEBATCH_SPRITES_MAX_PER_FLUSH *
     QUAD_VERTEX_COUNT
   );
+
+  errorChain(shaderBind(SPRITEBATCH.shader));
+  errorChain(shaderSetMaterial(SPRITEBATCH.shader, &SPRITEBATCH.material));
   errorChain(meshFlush(&SPRITEBATCH.mesh, vertexOffset, vertexCount));
   errorChain(meshDraw(&SPRITEBATCH.mesh, vertexOffset, vertexCount));
 

src/dusk/display/spritebatch/spritebatch.h

@@ -8,6 +8,7 @@
 #pragma once
 #include "display/mesh/quad.h"
 #include "display/texture/texture.h"
+#include "display/shader/shadermaterial.h"
 
 #define SPRITEBATCH_SPRITES_MAX 512
 #define SPRITEBATCH_VERTEX_COUNT (SPRITEBATCH_SPRITES_MAX * QUAD_VERTEX_COUNT)
@@ -21,146 +22,66 @@ typedef struct {
   vec3 max;
   vec2 uvMin;
   vec2 uvMax;
-  texture_t *texture;
-#if MESH_ENABLE_COLOR
-  color_t color;
-#endif
 } spritebatchsprite_t;
 
 typedef struct {
   mesh_t mesh;
   int32_t spriteCount;
   int32_t spriteFlush;
-  texture_t *currentTexture;
+
+  shader_t *shader;
+  shadermaterial_t material;
 } spritebatch_t;
 
-// Have to define these seperately because of alignment in certain platforms.
+// Have to define these separately because of alignment on certain platforms.
 extern meshvertex_t SPRITEBATCH_VERTICES[SPRITEBATCH_VERTEX_COUNT];
 extern spritebatch_t SPRITEBATCH;
 
 /**
- * Initializes a sprite batch.
+ * Initializes the global sprite batch and its internal mesh buffer.
  *
- * @return An error code indicating success or failure.
+ * @return Error state.
  */
 errorret_t spriteBatchInit();
 
 /**
- * Buffers an array of sprites. Flushes automatically when the texture changes
+ * Lowest-level buffer function. Writes sprites into the internal vertex buffer.
- * or the per-flush limit is reached.
+ * Flushes automatically when the per-flush capacity is reached. Does not
+ * modify material state — call spriteBatchSetState or use a high-level push
+ * function before buffering.
  *
  * @param sprites Pointer to the sprite array.
  * @param count Number of sprites to buffer.
- * @return An error code indicating success or failure.
+ * @param shader Shader to use when flushing.
+ * @param material Material information passed to the shader when flushing.
+ * @return Error state.
  */
 errorret_t spriteBatchBuffer(
   const spritebatchsprite_t *sprites,
-  const uint32_t count
+  const uint32_t count,
+  shader_t *shader,
+  const shadermaterial_t material
 );
 
 /**
- * Convenience wrapper — buffers a single sprite.
+ * Resets sprite and flush counters and clears the current material state.
- *
+ * Calling spriteBatchFlush after this renders nothing.
- * @param sprite The sprite to buffer.
- * @return An error code indicating success or failure.
- */
-errorret_t spriteBatchBufferSprite(const spritebatchsprite_t *sprite);
-
-/**
- * Pushes multiple sprites to the batch using parallel arrays of values.
- *
- * @param minX Array of minimum x coordinates.
- * @param minY Array of minimum y coordinates.
- * @param maxX Array of maximum x coordinates.
- * @param maxY Array of maximum y coordinates.
- * @param z Array of z coordinates.
- * @param color Array of colors (if enabled).
- * @param u0 Array of u0 texture coordinates.
- * @param v0 Array of v0 texture coordinates.
- * @param u1 Array of u1 texture coordinates.
- * @param v1 Array of v1 texture coordinates.
- * @param count Number of sprites to push.
- * @return An error code indicating success or failure.
- */
-errorret_t spriteBatchPushv(
-  const float_t *minX,
-  const float_t *minY,
-  const float_t *maxX,
-  const float_t *maxY,
-  const float_t *z,
-#if MESH_ENABLE_COLOR
-  const color_t *color,
-#endif
-  const float_t *u0,
-  const float_t *v0,
-  const float_t *u1,
-  const float_t *v1,
-  const size_t count
-);
-
-/**
- * Pushes a 2D sprite (z=0) to the batch.
- *
- * @param minX The minimum x coordinate of the sprite.
- * @param minY The minimum y coordinate of the sprite.
- * @param maxX The maximum x coordinate of the sprite.
- * @param maxY The maximum y coordinate of the sprite.
- * @param color The color to tint the sprite with.
- * @param u0 Texture u coordinate for the top-left corner.
- * @param v0 Texture v coordinate for the top-left corner.
- * @param u1 Texture u coordinate for the bottom-right corner.
- * @param v1 Texture v coordinate for the bottom-right corner.
- * @return An error code indicating success or failure.
- */
-errorret_t spriteBatchPush(
-  const float_t minX,
-  const float_t minY,
-  const float_t maxX,
-  const float_t maxY,
-  #if MESH_ENABLE_COLOR
-    const color_t color,
-  #endif
-  const float_t u0,
-  const float_t v0,
-  const float_t u1,
-  const float_t v1
-);
-
-/**
- * Pushes a 3D sprite to the batch.
- *
- * @param min The minimum (x,y,z) coordinate of the sprite.
- * @param max The maximum (x,y,z) coordinate of the sprite.
- * @param color The color to tint the sprite with.
- * @param uvMin Texture coordinate for the top-left corner.
- * @param uvMax Texture coordinate for the bottom-right corner.
- * @return An error code indicating success or failure.
- */
-errorret_t spriteBatchPushZ(
-  const vec3 min,
-  const vec3 max,
-  #if MESH_ENABLE_COLOR
-    const color_t color,
-  #endif
-  const vec2 uvMin,
-  const vec2 uvMax
-);
-
-/**
- * Clears the sprite batch. Calling flush after this renders nothing.
  */
 void spriteBatchClear();
 
 /**
- * Flushes the sprite batch, rendering all queued sprites.
+ * Uploads and draws all buffered sprites. If a material type has been set via
+ * spriteBatchSetState or spriteBatchCheckState, the shader is bound and the
+ * material is applied first. If matType is NULL the caller is responsible for
+ * having the correct shader already bound. Does nothing if the buffer is empty.
  *
- * @return An error code indicating success or failure.
+ * @return Error state.
  */
 errorret_t spriteBatchFlush();
 
 /**
- * Disposes of the sprite batch, freeing any allocated resources.
+ * Disposes of the sprite batch and frees its internal mesh buffer.
  *
- * @return An error code indicating success or failure.
+ * @return Error state.
  */
 errorret_t spriteBatchDispose();

src/dusk/display/text/font.h

@@ -10,6 +10,6 @@
 #include "display/texture/tileset.h"
 
 typedef struct {
-  texture_t texture;
+  texture_t *texture;
-  tileset_t tileset;
+  tileset_t *tileset;
 } font_t;

src/dusk/display/text/text.c

@@ -9,6 +9,7 @@
 #include "assert/assert.h"
 #include "util/memory.h"
 #include "display/spritebatch/spritebatch.h"
+#include "asset/asset.h"
 #include "asset/loader/display/assettextureloader.h"
 #include "asset/loader/display/assettilesetloader.h"
 #include "display/shader/shaderunlit.h"
@@ -16,49 +17,60 @@
 font_t FONT_DEFAULT;
 
 errorret_t textInit(void) {
-  errorChain(assetTextureLoad(
+  assetloaderinput_t input = { .texture = TEXTURE_FORMAT_RGBA };
-    "ui/minogram.png", &FONT_DEFAULT.texture, TEXTURE_FORMAT_RGBA
+  assetentry_t *entryTexture = assetLock(
-  ));
+    "ui/minogram.png", ASSET_LOADER_TYPE_TEXTURE, &input
-  errorChain(assetTilesetLoad("ui/minogram.dtf", &FONT_DEFAULT.tileset));
+  );
+  assetentry_t *entryTileset = assetLock(
+    "ui/minogram.dtf", ASSET_LOADER_TYPE_TILESET, NULL
+  );
+  errorChain(assetRequireLoaded(entryTexture));
+  errorChain(assetRequireLoaded(entryTileset));
+
+  FONT_DEFAULT.texture = &entryTexture->data.texture;
+  FONT_DEFAULT.tileset = &entryTileset->data.tileset;
   errorOk();
 }
 
 errorret_t textDispose(void) {
-  errorChain(textureDispose(&FONT_DEFAULT.texture));
+  FONT_DEFAULT.texture = NULL;
+  FONT_DEFAULT.tileset = NULL;
+  assetUnlock("ui/minogram.png");
+  assetUnlock("ui/minogram.dtf");
   errorOk();
 }
 
-errorret_t textDrawChar(
+spritebatchsprite_t textGetSprite(
-  const float_t x,
+  const vec2 pos, const char_t c, const font_t *font
-  const float_t y,
-  const char_t c,
-  #if MESH_ENABLE_COLOR
-    const color_t color,
-  #endif
-  font_t *font
 ) {
+  assertNotNull(font, "Font cannot be NULL");
+
+  // Change char from ASCII to a tile index.
   int32_t tileIndex = (int32_t)(c) - TEXT_CHAR_START;
-  if(tileIndex < 0 || tileIndex >= font->tileset.tileCount) {
+  if(tileIndex < 0 || tileIndex >= font->tileset->tileCount) {
     tileIndex = ((int32_t)'@') - TEXT_CHAR_START;
   }
   assertTrue(
-    tileIndex >= 0 && tileIndex <= font->tileset.tileCount,
+    tileIndex >= 0 && tileIndex <= font->tileset->tileCount,
     "Character is out of bounds for font tiles"
   );
 
+  // Create sprite.
   vec4 uv;
-  tilesetTileGetUV(&font->tileset, tileIndex, uv);
+  tilesetTileGetUV(font->tileset, tileIndex, uv);
 
-  errorChain(spriteBatchPush(
+  spritebatchsprite_t sprite;
-    x, y,
+  sprite.min[0] = pos[0];
-    x + font->tileset.tileWidth,
+  sprite.min[1] = pos[1];
-    y + font->tileset.tileHeight,
+  sprite.min[2] = 0.0f;
-    #if MESH_ENABLE_COLOR
+  sprite.max[0] = pos[0] + font->tileset->tileWidth;
-      color,
+  sprite.max[1] = pos[1] + font->tileset->tileHeight;
-    #endif
+  sprite.max[2] = 0.0f;
-    uv[0], uv[1], uv[2], uv[3]
+  sprite.uvMin[0] = uv[0];
-  ));
+  sprite.uvMin[1] = uv[1];
-  errorOk();
+  sprite.uvMax[0] = uv[2];
+  sprite.uvMax[1] = uv[3];
+  return sprite;
 }
 
 errorret_t textDraw(
@@ -70,10 +82,20 @@ errorret_t textDraw(
 ) {
   assertNotNull(text, "Text cannot be NULL");
 
+  spritebatchsprite_t sprite;
+  shadermaterial_t material = {
+    .unlit = {
+      .color = color,
+      .texture = font->texture
+    }
+  };
+
   float_t posX = x;
   float_t posY = y;
 
-  errorChain(shaderSetTexture(&SHADER_UNLIT, SHADER_UNLIT_TEXTURE, &font->texture));
+  errorChain(shaderSetTexture(
+    &SHADER_UNLIT, SHADER_UNLIT_TEXTURE, font->texture
+  ));
 
   #if MESH_ENABLE_COLOR
   #else
@@ -85,23 +107,18 @@ errorret_t textDraw(
   while((c = text[i++]) != '\0') {
     if(c == '\n') {
       posX = x;
-      posY += font->tileset.tileHeight;
+      posY += font->tileset->tileHeight;
       continue;
     }
 
     if(c == ' ') {
-      posX += font->tileset.tileWidth;
+      posX += font->tileset->tileWidth;
       continue;
     }
 
-    errorChain(textDrawChar(
+    sprite = textGetSprite((vec2){posX, posY}, c, font);
-      posX, posY, c,
+    errorChain(spriteBatchBuffer(&sprite, 1, &SHADER_UNLIT, material));
-      #if MESH_ENABLE_COLOR
+    posX += font->tileset->tileWidth;
-        color,
-      #endif
-      font
-    ));
-    posX += font->tileset.tileWidth;
   }
   errorOk();
 }
@@ -117,7 +134,7 @@ void textMeasure(
   assertNotNull(outHeight, "Output height pointer cannot be NULL");
 
   int32_t width = 0;
-  int32_t height = font->tileset.tileHeight;
+  int32_t height = font->tileset->tileHeight;
   int32_t lineWidth = 0;
 
   char_t c;
@@ -126,11 +143,11 @@ void textMeasure(
     if(c == '\n') {
       if(lineWidth > width) width = lineWidth;
       lineWidth = 0;
-      height += font->tileset.tileHeight;
+      height += font->tileset->tileHeight;
       continue;
     }
 
-    lineWidth += font->tileset.tileWidth;
+    lineWidth += font->tileset->tileWidth;
   }
 
   if(lineWidth > width) width = lineWidth;

src/dusk/display/text/text.h

@@ -8,6 +8,7 @@
 #pragma once
 #include "asset/asset.h"
 #include "display/text/font.h"
+#include "display/spritebatch/spritebatch.h"
 
 #define TEXT_CHAR_START '!'
 
@@ -28,23 +29,17 @@ errorret_t textInit(void);
 errorret_t textDispose(void);
 
 /**
- * Draws a single character at the specified position.
+ * Builds a sprite for a single character at the given position.
  *
- * @param x The x-coordinate to draw the character at.
+ * @param pos The (x, y) position of the character in screen/world space.
- * @param y The y-coordinate to draw the character at.
+ * @param c The character to build a sprite for.
- * @param c The character to draw.
+ * @param font Font to use for tile lookup.
- * @param color The color to draw the character in.
+ * @return The populated sprite ready for spriteBatchBuffer.
- * @param font Font to use for rendering.
- * @return Either an error or success result.
  */
-errorret_t textDrawChar(
+spritebatchsprite_t textGetSprite(
-  const float_t x,
+  const vec2 pos,
-  const float_t y,
   const char_t c,
-  #if MESH_ENABLE_COLOR
+  const font_t *font
-    const color_t color,
-  #endif
-  font_t *font
 );
 
 /**

src/dusk/engine/engine.c

@@ -23,11 +23,10 @@
 #include "network/network.h"
 #include "system/system.h"
 #include "console/console.h"
+#include "script/script.h"
 #include "item/backpack.h"
 #include "save/save.h"
 
-#include "scene/initial/initialscene.h"
-
 engine_t ENGINE;
 
 errorret_t engineInit(const int32_t argc, const char_t **argv) {
@@ -35,6 +34,7 @@ errorret_t engineInit(const int32_t argc, const char_t **argv) {
   ENGINE.running = true;
   ENGINE.argc = argc;
   ENGINE.argv = argv;
+  ENGINE.version = DUSK_VERSION;
 
   // Init systems. Order is important.
   errorChain(systemInit());
@@ -55,9 +55,10 @@ errorret_t engineInit(const int32_t argc, const char_t **argv) {
   physicsManagerInit();
   errorChain(networkInit());
 
-  /* Run the init script. */
+  errorChain(scriptInit());
+  errorChain(scriptExecFile("init.js"));
+
   consolePrint("Engine initialized");
-  sceneSet(SCENE_TYPE_INITIAL);
 
   errorOk();
 }
@@ -68,18 +69,16 @@ errorret_t engineUpdate(void) {
   timeUpdate();
   inputUpdate();
   consoleUpdate();
+  entityManagerUpdate();
   uiUpdate();
   errorChain(uiTextboxUpdate());
   physicsManagerUpdate();
   errorChain(displayUpdate());
-
-  if(inputPressed(INPUT_ACTION_RAGEQUIT)) ENGINE.running = false;
-
-  // Scene update occurs last because only after rendering would we want to do
-  // scene switching, refer to sceneSet() for information.
   errorChain(cutsceneUpdate());
   errorChain(sceneUpdate());
+  errorChain(assetUpdate());
 
+  if(inputPressed(INPUT_ACTION_RAGEQUIT)) ENGINE.running = false;
   errorOk();
 }
 
@@ -99,6 +98,7 @@ errorret_t engineDispose(void) {
   errorChain(displayDispose());
   // errorChain(saveDispose());
   errorChain(assetDispose());
+  errorChain(scriptDispose());
 
   errorOk();
 }

src/dusk/engine/engine.h

@@ -15,6 +15,7 @@ typedef struct {
   bool_t running;
   int32_t argc;
   const char_t **argv;
+  const char_t *version;
 } engine_t;
 
 extern engine_t ENGINE;

src/dusk/entity/component.c

@@ -12,12 +12,13 @@
 componentdefinition_t COMPONENT_DEFINITIONS[] = {
   [COMPONENT_TYPE_NULL] = { 0 },
 
-  #define X(enm, type, field, iMethod, dMethod) \
+  #define X(enm, type, field, iMethod, dMethod, rMethod) \
     [COMPONENT_TYPE_##enm] = { \
       .enumName = #enm, \
       .name = #field, \
       .init = iMethod, \
-      .dispose = dMethod \
+      .dispose = dMethod, \
+      .render = rMethod \
     },
   
   #include "componentlist.h"
@@ -114,6 +115,19 @@ entityid_t componentGetEntitiesWithComponent(
   return written;
 }
 
+errorret_t componentRenderAll(void) {
+  for(entityid_t eid = 0; eid < ENTITY_COUNT_MAX; eid++) {
+    if(!(ENTITY_MANAGER.entities[eid].state & ENTITY_STATE_ACTIVE)) continue;
+    for(componentid_t cid = 0; cid < ENTITY_COMPONENT_COUNT_MAX; cid++) {
+      component_t *cmp = &ENTITY_MANAGER.components[componentGetIndex(eid, cid)];
+      if(cmp->type == COMPONENT_TYPE_NULL) continue;
+      if(!COMPONENT_DEFINITIONS[cmp->type].render) continue;
+      errorChain(COMPONENT_DEFINITIONS[cmp->type].render(eid, cid));
+    }
+  }
+  errorOk();
+}
+
 void componentDispose(
   const entityid_t entityId,
   const componentid_t componentId

src/dusk/entity/component.h

@@ -8,13 +8,13 @@
 #pragma once
 #include "entitybase.h"
 
-#define X(enumName, type, field, init, dispose) \
+#define X(enumName, type, field, init, dispose, render) \
   // do nothing
 #include "componentlist.h"
 #undef X
 
 typedef union {
-  #define X(enumName, type, field, init, dispose) type field;
+  #define X(enumName, type, field, init, dispose, render) type field;
   #include "componentlist.h"
   #undef X
 } componentdata_t;
@@ -24,12 +24,13 @@ typedef struct {
   const char_t *name;
   void (*init)(const entityid_t, const componentid_t);
   void (*dispose)(const entityid_t, const componentid_t);
+  errorret_t (*render)(const entityid_t, const componentid_t);
 } componentdefinition_t;
 
 typedef enum {
   COMPONENT_TYPE_NULL,
 
-  #define X(enumName, type, field, init, dispose) \
+  #define X(enumName, type, field, init, dispose, render) \
     COMPONENT_TYPE_##enumName,
   #include "componentlist.h"
   #undef X
@@ -108,3 +109,12 @@ void componentDispose(
   const entityid_t entityId,
   const componentid_t componentId
 );
+
+/**
+ * Calls the render callback on every active component that defines one.
+ * Iterates all active entities and all their component slots. No-op for
+ * components whose definition has render == NULL.
+ *
+ * @return Error state.
+ */
+errorret_t componentRenderAll(void);

src/dusk/entity/component/CMakeLists.txt

@@ -4,6 +4,7 @@
 # https://opensource.org/licenses/MIT
 
 add_subdirectory(display)
+add_subdirectory(overworld)
 add_subdirectory(physics)
 add_subdirectory(script)
 add_subdirectory(trigger)

src/dusk/entity/component/display/entitycamera.c

@@ -16,7 +16,7 @@ void entityCameraInit(const entityid_t ent, const componentid_t comp) {
     ent, comp, COMPONENT_TYPE_CAMERA
   );
   cam->nearClip = 0.1f;
-  cam->farClip = 100.0f;
+  cam->farClip = 5000.0f;
   cam->projType = ENTITY_CAMERA_PROJECTION_TYPE_PERSPECTIVE;
   cam->perspective.fov = glm_rad(45.0f);
 }
@@ -66,7 +66,7 @@ entityid_t entityCameraGetCurrent(void) {
   entityid_t count = componentGetEntitiesWithComponent(
     COMPONENT_TYPE_CAMERA, camEnts, camComps
   );
-  if(count == 0) return ENTITY_COUNT_MAX;
+  if(count == 0) return ENTITY_ID_INVALID;
   return camEnts[0];
 }
 
@@ -83,6 +83,30 @@ void entityCameraGetForward(const entityid_t entityId, vec2 out) {
   out[1] = fz;
 }
 
+void entityCameraLookAtPixelPerfect(
+  const entityid_t ent,
+  const componentid_t posComp,
+  const componentid_t camComp,
+  const vec3 point,
+  const vec3 eyeOffset,
+  const float_t scale
+) {
+  entitycamera_t *cam = (entitycamera_t *)componentGetData(
+    ent, camComp, COMPONENT_TYPE_CAMERA
+  );
+  float_t dist = (
+    (float_t)SCREEN.height / (2.0f * scale * tanf(cam->perspective.fov * 0.5f))
+  );
+
+  vec3 eye = {
+    point[0] + eyeOffset[0],
+    point[1] + dist + eyeOffset[1],
+    point[2] + eyeOffset[2]
+  };
+  vec3 up = { 0.0f, 0.0f, -1.0f };
+  entityPositionLookAt(ent, posComp, eye, (float_t *)point, up);
+}
+
 void entityCameraGetRight(const entityid_t entityId, vec2 out) {
   componentid_t posComp = entityGetComponent(entityId, COMPONENT_TYPE_POSITION);
   entityposition_t *pos = entityPositionGet(entityId, posComp);

src/dusk/entity/component/display/entitycamera.h

@@ -55,7 +55,7 @@ void entityCameraGetProjection(
 );
 
 /**
- * Returns the entity ID of the first active camera, or ENTITY_COUNT_MAX if 
+ * Returns the entity ID of the first active camera, or ENTITY_ID_INVALID if
  * none are active.
  */
 entityid_t entityCameraGetCurrent(void);
@@ -77,3 +77,23 @@ void entityCameraGetForward(const entityid_t entityId, vec2 out);
  * @param out Output vec2: {rightX, rightZ} normalized.
  */
 void entityCameraGetRight(const entityid_t entityId, vec2 out);
+
+/**
+ * Positions the camera to look at a 3D point at a pixel-perfect distance
+ * derived from the camera's FOV and screen height.
+ *
+ * @param ent The camera entity ID.
+ * @param posComp The position component ID.
+ * @param camComp The camera component ID.
+ * @param point World position to look at.
+ * @param eyeOffset Offset added to the eye position only (not the target).
+ * @param scale Pixels per world unit. 1.0 = pixel perfect, 2.0 = 2px per unit.
+ */
+void entityCameraLookAtPixelPerfect(
+  const entityid_t ent,
+  const componentid_t posComp,
+  const componentid_t camComp,
+  const vec3 point,
+  const vec3 eyeOffset,
+  const float_t scale
+);

src/dusk/entity/component/display/entityposition.c

@@ -7,25 +7,82 @@
 
 #include "entity/entitymanager.h"
 
-// Lazily recompute worldTransform from the parent chain.
+// Decompose localTransform into the PRS cache. Only called when PRS_DIRTY.
-static void entityPositionUpdateWorld(entityposition_t *pos) {
+static void entityPositionEnsurePRS(entityposition_t *pos) {
-  if(!pos->dirty) return;
+  if(!(pos->flags & ENTITY_POSITION_FLAG_PRS_DIRTY)) return;
+  entityPositionDecompose(pos);
+  pos->flags &= ~ENTITY_POSITION_FLAG_PRS_DIRTY;
+}
 
-  if(pos->parentEntityId == ENTITY_ID_INVALID) {
+// Rebuild localTransform from the PRS cache. Only rebuilds what changed.
-    glm_mat4_copy(pos->localTransform, pos->worldTransform);
+static void entityPositionEnsureLocal(entityposition_t *pos) {
-  } else {
+  const uint8_t dirty = pos->flags & (
+    ENTITY_POSITION_FLAG_ROTATION_DIRTY | ENTITY_POSITION_FLAG_POSITION_DIRTY
+  );
+  if(!dirty) return;
+
+  if(dirty & ENTITY_POSITION_FLAG_ROTATION_DIRTY) {
+    // Rotation or scale changed: rebuild columns 0-2 analytically (XYZ euler order).
+    const float c0 = cosf(pos->rotation[0]), s0 = sinf(pos->rotation[0]);
+    const float c1 = cosf(pos->rotation[1]), s1 = sinf(pos->rotation[1]);
+    const float c2 = cosf(pos->rotation[2]), s2 = sinf(pos->rotation[2]);
+    const float s0s1 = s0 * s1;
+    const float c0s1 = c0 * s1;
+
+    pos->localTransform[0][0] =  c1 * c2                  * pos->scale[0];
+    pos->localTransform[0][1] = (c0 * s2 + s0s1 * c2)     * pos->scale[0];
+    pos->localTransform[0][2] = (s0 * s2 - c0s1 * c2)     * pos->scale[0];
+    pos->localTransform[0][3] = 0.0f;
+
+    pos->localTransform[1][0] = -c1 * s2                  * pos->scale[1];
+    pos->localTransform[1][1] = (c0 * c2 - s0s1 * s2)     * pos->scale[1];
+    pos->localTransform[1][2] = (s0 * c2 + c0s1 * s2)     * pos->scale[1];
+    pos->localTransform[1][3] = 0.0f;
+
+    pos->localTransform[2][0] =  s1                        * pos->scale[2];
+    pos->localTransform[2][1] = -s0 * c1                   * pos->scale[2];
+    pos->localTransform[2][2] =  c0 * c1                   * pos->scale[2];
+    pos->localTransform[2][3] = 0.0f;
+  }
+
+  if(dirty & ENTITY_POSITION_FLAG_POSITION_DIRTY) {
+    // Only position changed: update column 3 only (no trig needed).
+    pos->localTransform[3][0] = pos->position[0];
+    pos->localTransform[3][1] = pos->position[1];
+    pos->localTransform[3][2] = pos->position[2];
+    pos->localTransform[3][3] = 1.0f;
+  }
+
+  pos->flags &= ~(ENTITY_POSITION_FLAG_ROTATION_DIRTY | ENTITY_POSITION_FLAG_POSITION_DIRTY);
+}
+
+// Recompute worldTransform from the parent chain. Only called when WORLD_DIRTY.
+static void entityPositionEnsureWorld(entityposition_t *pos) {
+  if(!(pos->flags & ENTITY_POSITION_FLAG_WORLD_DIRTY)) return;
+  entityPositionEnsureLocal(pos);
+
+  if(pos->parentEntityId != ENTITY_ID_INVALID) {
+    // Parented: world = parent.world × local. worldTransform must be written
+    // because children (and this node's getters) read it.
     entityposition_t *parent = componentGetData(
       pos->parentEntityId, pos->parentComponentId, COMPONENT_TYPE_POSITION
     );
-    entityPositionUpdateWorld(parent);
+    entityPositionEnsureWorld(parent);
     glm_mat4_mul(parent->worldTransform, pos->localTransform, pos->worldTransform);
+  } else if(pos->childCount > 0) {
+    // Parentless root with children: children need a valid worldTransform to
+    // multiply against, but world == local, so just copy.
+    glm_mat4_copy(pos->localTransform, pos->worldTransform);
   }
+  // Parentless leaf: world == local. Getters read localTransform directly;
+  // no copy needed.
 
-  pos->dirty = false;
+  pos->flags &= ~ENTITY_POSITION_FLAG_WORLD_DIRTY;
 }
 
 void entityPositionMarkDirty(entityposition_t *pos) {
-  pos->dirty = true;
+  if(pos->flags & ENTITY_POSITION_FLAG_WORLD_DIRTY) return;
+  pos->flags |= ENTITY_POSITION_FLAG_WORLD_DIRTY;
   for(uint8_t i = 0; i < pos->childCount; i++) {
     entityposition_t *child = componentGetData(
       pos->childEntityIds[i], pos->childComponentIds[i], COMPONENT_TYPE_POSITION
@@ -42,29 +99,31 @@ void entityPositionInit(
     entityId, componentId, COMPONENT_TYPE_POSITION
   );
 
+  pos->flags = 0;
+  pos->parentEntityId = ENTITY_ID_INVALID;
+  pos->parentComponentId = COMPONENT_ID_INVALID;
+  pos->childCount = 0;
   glm_vec3_zero(pos->position);
   glm_vec3_zero(pos->rotation);
   glm_vec3_one(pos->scale);
   glm_mat4_identity(pos->localTransform);
   glm_mat4_identity(pos->worldTransform);
-  pos->dirty = false;
-  pos->parentEntityId = ENTITY_ID_INVALID;
-  pos->parentComponentId = COMPONENT_ID_INVALID;
-  pos->childCount = 0;
 }
 
 void entityPositionLookAt(
   const entityid_t entityId,
   const componentid_t componentId,
+  vec3 eye,
   vec3 target,
-  vec3 up,
+  vec3 up
-  vec3 eye
 ) {
   entityposition_t *pos = componentGetData(
     entityId, componentId, COMPONENT_TYPE_POSITION
   );
   glm_lookat(eye, target, up, pos->localTransform);
-  entityPositionDecompose(pos);
+  // localTransform is now authoritative; PRS cache is stale.
+  pos->flags = (pos->flags | ENTITY_POSITION_FLAG_PRS_DIRTY)
+             & ~(ENTITY_POSITION_FLAG_ROTATION_DIRTY | ENTITY_POSITION_FLAG_POSITION_DIRTY);
   entityPositionMarkDirty(pos);
 }
 
@@ -76,8 +135,11 @@ void entityPositionGetTransform(
   entityposition_t *pos = componentGetData(
     entityId, componentId, COMPONENT_TYPE_POSITION
   );
-  entityPositionUpdateWorld(pos);
+  entityPositionEnsureWorld(pos);
-  glm_mat4_copy(pos->worldTransform, dest);
+  glm_mat4_copy(
+    pos->parentEntityId == ENTITY_ID_INVALID ? pos->localTransform : pos->worldTransform,
+    dest
+  );
 }
 
 void entityPositionGetLocalTransform(
@@ -88,10 +150,11 @@ void entityPositionGetLocalTransform(
   entityposition_t *pos = componentGetData(
     entityId, componentId, COMPONENT_TYPE_POSITION
   );
+  entityPositionEnsureLocal(pos);
   glm_mat4_copy(pos->localTransform, dest);
 }
 
-void entityPositionGetPosition(
+void entityPositionGetLocalPosition(
   const entityid_t entityId,
   const componentid_t componentId,
   vec3 dest
@@ -99,10 +162,59 @@ void entityPositionGetPosition(
   entityposition_t *pos = componentGetData(
     entityId, componentId, COMPONENT_TYPE_POSITION
   );
+  entityPositionEnsurePRS(pos);
   glm_vec3_copy(pos->position, dest);
 }
 
-void entityPositionSetPosition(
+void entityPositionGetWorldPosition(
+  const entityid_t entityId,
+  const componentid_t componentId,
+  vec3 dest
+) {
+  entityposition_t *pos = componentGetData(
+    entityId, componentId, COMPONENT_TYPE_POSITION
+  );
+  if(pos->parentEntityId == ENTITY_ID_INVALID) {
+    entityPositionEnsurePRS(pos);
+    glm_vec3_copy(pos->position, dest);
+    return;
+  }
+  entityPositionEnsureWorld(pos);
+  dest[0] = pos->worldTransform[3][0];
+  dest[1] = pos->worldTransform[3][1];
+  dest[2] = pos->worldTransform[3][2];
+}
+
+void entityPositionSetWorldPosition(
+  const entityid_t entityId,
+  const componentid_t componentId,
+  vec3 position
+) {
+  entityposition_t *pos = componentGetData(
+    entityId, componentId, COMPONENT_TYPE_POSITION
+  );
+  if(pos->parentEntityId == ENTITY_ID_INVALID) {
+    glm_vec3_copy(position, pos->position);
+    pos->flags = (pos->flags | ENTITY_POSITION_FLAG_POSITION_DIRTY)
+               & ~ENTITY_POSITION_FLAG_PRS_DIRTY;
+    entityPositionMarkDirty(pos);
+    return;
+  }
+  entityposition_t *parent = componentGetData(
+    pos->parentEntityId, pos->parentComponentId, COMPONENT_TYPE_POSITION
+  );
+  entityPositionEnsureWorld(parent);
+  mat4 invParent;
+  glm_mat4_inv(parent->worldTransform, invParent);
+  vec3 localPos;
+  glm_mat4_mulv3(invParent, position, 1.0f, localPos);
+  glm_vec3_copy(localPos, pos->position);
+  pos->flags = (pos->flags | ENTITY_POSITION_FLAG_POSITION_DIRTY)
+             & ~ENTITY_POSITION_FLAG_PRS_DIRTY;
+  entityPositionMarkDirty(pos);
+}
+
+void entityPositionSetLocalPosition(
   const entityid_t entityId,
   const componentid_t componentId,
   vec3 position
@@ -111,10 +223,12 @@ void entityPositionSetPosition(
     entityId, componentId, COMPONENT_TYPE_POSITION
   );
   glm_vec3_copy(position, pos->position);
-  entityPositionRebuild(pos);
+  pos->flags = (pos->flags | ENTITY_POSITION_FLAG_POSITION_DIRTY)
+             & ~ENTITY_POSITION_FLAG_PRS_DIRTY;
+  entityPositionMarkDirty(pos);
 }
 
-void entityPositionGetRotation(
+void entityPositionGetLocalRotation(
   const entityid_t entityId,
   const componentid_t componentId,
   vec3 dest
@@ -122,10 +236,48 @@ void entityPositionGetRotation(
   entityposition_t *pos = componentGetData(
     entityId, componentId, COMPONENT_TYPE_POSITION
   );
+  entityPositionEnsurePRS(pos);
   glm_vec3_copy(pos->rotation, dest);
 }
 
-void entityPositionSetRotation(
+void entityPositionGetWorldRotation(
+  const entityid_t entityId,
+  const componentid_t componentId,
+  vec3 dest
+) {
+  entityposition_t *pos = componentGetData(
+    entityId, componentId, COMPONENT_TYPE_POSITION
+  );
+  if(pos->parentEntityId == ENTITY_ID_INVALID) {
+    entityPositionEnsurePRS(pos);
+    glm_vec3_copy(pos->rotation, dest);
+    return;
+  }
+  entityPositionEnsureWorld(pos);
+  const float (*wt)[4] = pos->worldTransform;
+  const float sx = sqrtf(wt[0][0]*wt[0][0] + wt[0][1]*wt[0][1] + wt[0][2]*wt[0][2]);
+  const float sy = sqrtf(wt[1][0]*wt[1][0] + wt[1][1]*wt[1][1] + wt[1][2]*wt[1][2]);
+  const float sz = sqrtf(wt[2][0]*wt[2][0] + wt[2][1]*wt[2][1] + wt[2][2]*wt[2][2]);
+  const float r00 = sx > 0.0f ? wt[0][0]/sx : 0.0f;
+  const float r10 = sy > 0.0f ? wt[1][0]/sy : 0.0f;
+  const float r20 = sz > 0.0f ? wt[2][0]/sz : 0.0f;
+  const float r01 = sx > 0.0f ? wt[0][1]/sx : 0.0f;
+  const float r11 = sy > 0.0f ? wt[1][1]/sy : 0.0f;
+  const float r21 = sz > 0.0f ? wt[2][1]/sz : 0.0f;
+  const float r22 = sz > 0.0f ? wt[2][2]/sz : 0.0f;
+  const float sinBeta = glm_clamp(r20, -1.0f, 1.0f);
+  dest[1] = asinf(sinBeta);
+  const float cosBeta = cosf(dest[1]);
+  if(fabsf(cosBeta) > 1e-6f) {
+    dest[0] = atan2f(-r21, r22);
+    dest[2] = atan2f(-r10, r00);
+  } else {
+    dest[2] = 0.0f;
+    dest[0] = (sinBeta > 0.0f) ? atan2f(r01, r11) : -atan2f(r01, r11);
+  }
+}
+
+void entityPositionSetLocalRotation(
   const entityid_t entityId,
   const componentid_t componentId,
   vec3 rotation
@@ -134,10 +286,87 @@ void entityPositionSetRotation(
     entityId, componentId, COMPONENT_TYPE_POSITION
   );
   glm_vec3_copy(rotation, pos->rotation);
-  entityPositionRebuild(pos);
+  pos->flags = (pos->flags | ENTITY_POSITION_FLAG_ROTATION_DIRTY)
+             & ~ENTITY_POSITION_FLAG_PRS_DIRTY;
+  entityPositionMarkDirty(pos);
 }
 
-void entityPositionGetScale(
+void entityPositionSetWorldRotation(
+  const entityid_t entityId,
+  const componentid_t componentId,
+  vec3 rotation
+) {
+  entityposition_t *pos = componentGetData(
+    entityId, componentId, COMPONENT_TYPE_POSITION
+  );
+  if(pos->parentEntityId == ENTITY_ID_INVALID) {
+    glm_vec3_copy(rotation, pos->rotation);
+    pos->flags = (pos->flags | ENTITY_POSITION_FLAG_ROTATION_DIRTY)
+               & ~ENTITY_POSITION_FLAG_PRS_DIRTY;
+    entityPositionMarkDirty(pos);
+    return;
+  }
+  entityposition_t *parent = componentGetData(
+    pos->parentEntityId, pos->parentComponentId, COMPONENT_TYPE_POSITION
+  );
+  entityPositionEnsureWorld(parent);
+
+  // Build target world rotation matrix (unit scale) from XYZ euler.
+  const float c0 = cosf(rotation[0]), s0 = sinf(rotation[0]);
+  const float c1 = cosf(rotation[1]), s1 = sinf(rotation[1]);
+  const float c2 = cosf(rotation[2]), s2 = sinf(rotation[2]);
+  const float s0s1 = s0*s1, c0s1 = c0*s1;
+  // Named wr[col_stored][row_stored] matching cglm column-major layout.
+  const float wr00 =  c1*c2,             wr01 =  c0*s2 + s0s1*c2,  wr02 =  s0*s2 - c0s1*c2;
+  const float wr10 = -c1*s2,             wr11 =  c0*c2 - s0s1*s2,  wr12 =  s0*c2 + c0s1*s2;
+  const float wr20 =  s1,                wr21 = -s0*c1,             wr22 =  c0*c1;
+
+  // Normalize parent world columns to extract pure rotation.
+  const float (*pt)[4] = parent->worldTransform;
+  const float psx = sqrtf(pt[0][0]*pt[0][0] + pt[0][1]*pt[0][1] + pt[0][2]*pt[0][2]);
+  const float psy = sqrtf(pt[1][0]*pt[1][0] + pt[1][1]*pt[1][1] + pt[1][2]*pt[1][2]);
+  const float psz = sqrtf(pt[2][0]*pt[2][0] + pt[2][1]*pt[2][1] + pt[2][2]*pt[2][2]);
+  const float pr00 = psx > 0.f ? pt[0][0]/psx : 0.f;
+  const float pr01 = psx > 0.f ? pt[0][1]/psx : 0.f;
+  const float pr02 = psx > 0.f ? pt[0][2]/psx : 0.f;
+  const float pr10 = psy > 0.f ? pt[1][0]/psy : 0.f;
+  const float pr11 = psy > 0.f ? pt[1][1]/psy : 0.f;
+  const float pr12 = psy > 0.f ? pt[1][2]/psy : 0.f;
+  const float pr20 = psz > 0.f ? pt[2][0]/psz : 0.f;
+  const float pr21 = psz > 0.f ? pt[2][1]/psz : 0.f;
+  const float pr22 = psz > 0.f ? pt[2][2]/psz : 0.f;
+
+  // local_R = parent_R^T * world_R  (R^-1 == R^T for orthogonal matrices).
+  // Compute only the 7 entries of the local rotation matrix needed for XYZ
+  // euler extraction (stored column-major: [col][row] = math [row][col]).
+  // sinBeta  = stored[2][0] = math[0][2]
+  // r21/r22  = stored[2][1..2] = math[1..2][2]
+  // r10/r00  = stored[1][0], stored[0][0] = math[0][1], math[0][0]
+  // gimbal   = stored[0][1], stored[1][1] = math[1][0], math[1][1]
+  const float lr00  = pr00*wr00 + pr01*wr10 + pr02*wr20;  // math[0][0]
+  const float lr10  = pr00*wr01 + pr01*wr11 + pr02*wr21;  // math[0][1]
+  const float lr20  = pr00*wr02 + pr01*wr12 + pr02*wr22;  // math[0][2] → sinBeta
+  const float lr01  = pr10*wr00 + pr11*wr10 + pr12*wr20;  // math[1][0]
+  const float lr11  = pr10*wr01 + pr11*wr11 + pr12*wr21;  // math[1][1]
+  const float lr21  = pr10*wr02 + pr11*wr12 + pr12*wr22;  // math[1][2] → r21
+  const float lr22  = pr20*wr02 + pr21*wr12 + pr22*wr22;  // math[2][2] → r22
+
+  const float sinBeta = glm_clamp(lr20, -1.0f, 1.0f);
+  pos->rotation[1] = asinf(sinBeta);
+  const float cosBeta = cosf(pos->rotation[1]);
+  if(fabsf(cosBeta) > 1e-6f) {
+    pos->rotation[0] = atan2f(-lr21, lr22);
+    pos->rotation[2] = atan2f(-lr10, lr00);
+  } else {
+    pos->rotation[2] = 0.0f;
+    pos->rotation[0] = (sinBeta > 0.0f) ? atan2f(lr01, lr11) : -atan2f(lr01, lr11);
+  }
+  pos->flags = (pos->flags | ENTITY_POSITION_FLAG_ROTATION_DIRTY)
+             & ~ENTITY_POSITION_FLAG_PRS_DIRTY;
+  entityPositionMarkDirty(pos);
+}
+
+void entityPositionGetLocalScale(
   const entityid_t entityId,
   const componentid_t componentId,
   vec3 dest
@@ -145,10 +374,31 @@ void entityPositionGetScale(
   entityposition_t *pos = componentGetData(
     entityId, componentId, COMPONENT_TYPE_POSITION
   );
+  entityPositionEnsurePRS(pos);
   glm_vec3_copy(pos->scale, dest);
 }
 
-void entityPositionSetScale(
+void entityPositionGetWorldScale(
+  const entityid_t entityId,
+  const componentid_t componentId,
+  vec3 dest
+) {
+  entityposition_t *pos = componentGetData(
+    entityId, componentId, COMPONENT_TYPE_POSITION
+  );
+  if(pos->parentEntityId == ENTITY_ID_INVALID) {
+    entityPositionEnsurePRS(pos);
+    glm_vec3_copy(pos->scale, dest);
+    return;
+  }
+  entityPositionEnsureWorld(pos);
+  const float (*wt)[4] = pos->worldTransform;
+  dest[0] = sqrtf(wt[0][0]*wt[0][0] + wt[0][1]*wt[0][1] + wt[0][2]*wt[0][2]);
+  dest[1] = sqrtf(wt[1][0]*wt[1][0] + wt[1][1]*wt[1][1] + wt[1][2]*wt[1][2]);
+  dest[2] = sqrtf(wt[2][0]*wt[2][0] + wt[2][1]*wt[2][1] + wt[2][2]*wt[2][2]);
+}
+
+void entityPositionSetLocalScale(
   const entityid_t entityId,
   const componentid_t componentId,
   vec3 scale
@@ -157,7 +407,40 @@ void entityPositionSetScale(
     entityId, componentId, COMPONENT_TYPE_POSITION
   );
   glm_vec3_copy(scale, pos->scale);
-  entityPositionRebuild(pos);
+  pos->flags = (pos->flags | ENTITY_POSITION_FLAG_ROTATION_DIRTY)
+             & ~ENTITY_POSITION_FLAG_PRS_DIRTY;
+  entityPositionMarkDirty(pos);
+}
+
+void entityPositionSetWorldScale(
+  const entityid_t entityId,
+  const componentid_t componentId,
+  vec3 scale
+) {
+  entityposition_t *pos = componentGetData(
+    entityId, componentId, COMPONENT_TYPE_POSITION
+  );
+  if(pos->parentEntityId == ENTITY_ID_INVALID) {
+    glm_vec3_copy(scale, pos->scale);
+    pos->flags = (pos->flags | ENTITY_POSITION_FLAG_ROTATION_DIRTY)
+               & ~ENTITY_POSITION_FLAG_PRS_DIRTY;
+    entityPositionMarkDirty(pos);
+    return;
+  }
+  entityposition_t *parent = componentGetData(
+    pos->parentEntityId, pos->parentComponentId, COMPONENT_TYPE_POSITION
+  );
+  entityPositionEnsureWorld(parent);
+  const float (*pt)[4] = parent->worldTransform;
+  const float psx = sqrtf(pt[0][0]*pt[0][0] + pt[0][1]*pt[0][1] + pt[0][2]*pt[0][2]);
+  const float psy = sqrtf(pt[1][0]*pt[1][0] + pt[1][1]*pt[1][1] + pt[1][2]*pt[1][2]);
+  const float psz = sqrtf(pt[2][0]*pt[2][0] + pt[2][1]*pt[2][1] + pt[2][2]*pt[2][2]);
+  pos->scale[0] = psx > 0.0f ? scale[0] / psx : scale[0];
+  pos->scale[1] = psy > 0.0f ? scale[1] / psy : scale[1];
+  pos->scale[2] = psz > 0.0f ? scale[2] / psz : scale[2];
+  pos->flags = (pos->flags | ENTITY_POSITION_FLAG_ROTATION_DIRTY)
+             & ~ENTITY_POSITION_FLAG_PRS_DIRTY;
+  entityPositionMarkDirty(pos);
 }
 
 void entityPositionSetParent(
@@ -218,12 +501,8 @@ entityposition_t *entityPositionGet(
 }
 
 void entityPositionRebuild(entityposition_t *pos) {
-  glm_mat4_identity(pos->localTransform);
+  pos->flags = (pos->flags | ENTITY_POSITION_FLAG_ROTATION_DIRTY | ENTITY_POSITION_FLAG_POSITION_DIRTY)
-  glm_translate(pos->localTransform, pos->position);
+             & ~ENTITY_POSITION_FLAG_PRS_DIRTY;
-  glm_rotate_x(pos->localTransform, pos->rotation[0], pos->localTransform);
-  glm_rotate_y(pos->localTransform, pos->rotation[1], pos->localTransform);
-  glm_rotate_z(pos->localTransform, pos->rotation[2], pos->localTransform);
-  glm_scale(pos->localTransform, pos->scale);
   entityPositionMarkDirty(pos);
 }
 
@@ -281,36 +560,33 @@ void entityPositionDecompose(entityposition_t *pos) {
     pos->localTransform[2][2] * pos->localTransform[2][2]
   );
 
-  // Normalize columns to isolate the rotation matrix.
+  // Normalize columns to isolate the rotation matrix (9 floats, no mat4 needed).
-  float invS0 = pos->scale[0] > 0.0f ? 1.0f / pos->scale[0] : 0.0f;
+  const float invS0 = pos->scale[0] > 0.0f ? 1.0f / pos->scale[0] : 0.0f;
-  float invS1 = pos->scale[1] > 0.0f ? 1.0f / pos->scale[1] : 0.0f;
+  const float invS1 = pos->scale[1] > 0.0f ? 1.0f / pos->scale[1] : 0.0f;
-  float invS2 = pos->scale[2] > 0.0f ? 1.0f / pos->scale[2] : 0.0f;
+  const float invS2 = pos->scale[2] > 0.0f ? 1.0f / pos->scale[2] : 0.0f;
 
-  mat4 r;
+  const float r00 = pos->localTransform[0][0] * invS0;
-  glm_mat4_identity(r);
+  const float r01 = pos->localTransform[0][1] * invS0;
-  r[0][0] = pos->localTransform[0][0] * invS0;
+  const float r02 = pos->localTransform[0][2] * invS0;
-  r[0][1] = pos->localTransform[0][1] * invS0;
+  const float r10 = pos->localTransform[1][0] * invS1;
-  r[0][2] = pos->localTransform[0][2] * invS0;
+  const float r11 = pos->localTransform[1][1] * invS1;
-  r[1][0] = pos->localTransform[1][0] * invS1;
+  const float r20 = pos->localTransform[2][0] * invS2;
-  r[1][1] = pos->localTransform[1][1] * invS1;
+  const float r21 = pos->localTransform[2][1] * invS2;
-  r[1][2] = pos->localTransform[1][2] * invS1;
+  const float r22 = pos->localTransform[2][2] * invS2;
-  r[2][0] = pos->localTransform[2][0] * invS2;
-  r[2][1] = pos->localTransform[2][1] * invS2;
-  r[2][2] = pos->localTransform[2][2] * invS2;
 
   // Extract XYZ euler angles (R = Rx * Ry * Rz, column-major)
-  float sinBeta = glm_clamp(r[2][0], -1.0f, 1.0f);
+  const float sinBeta = glm_clamp(r20, -1.0f, 1.0f);
   pos->rotation[1] = asinf(sinBeta);
-  float cosBeta = cosf(pos->rotation[1]);
+  const float cosBeta = cosf(pos->rotation[1]);
 
   if(fabsf(cosBeta) > 1e-6f) {
-    pos->rotation[0] = atan2f(-r[2][1], r[2][2]);
+    pos->rotation[0] = atan2f(-r21, r22);
-    pos->rotation[2] = atan2f(-r[1][0], r[0][0]);
+    pos->rotation[2] = atan2f(-r10, r00);
   } else {
     // Gimbal lock: pin Z to 0, recover X.
     pos->rotation[2] = 0.0f;
     pos->rotation[0] = (sinBeta > 0.0f)
-      ? atan2f(r[0][1], r[1][1])
+      ? atan2f(r01, r11)
-      : -atan2f(r[0][1], r[1][1]);
+      : -atan2f(r01, r11);
   }
 }

src/dusk/entity/component/display/entityposition.h

@@ -8,24 +8,81 @@
 #pragma once
 #include "entity/entitybase.h"
 
+/** Maximum number of child position components this node can track. */
 #define ENTITY_POSITION_CHILDREN_MAX 8
 
+/**
+ * PRS cache is stale. localTransform was written directly (e.g. lookAt) and
+ * position/rotation/scale need to be decomposed before they can be read.
+ */
+#define ENTITY_POSITION_FLAG_PRS_DIRTY   (1 << 0)
+
+/**
+ * Columns 0-2 of localTransform are stale. Rotation or scale changed; the
+ * basis vectors need to be rebuilt analytically before the matrix can be used.
+ * Does not imply column 3 (translation) is stale.
+ */
+#define ENTITY_POSITION_FLAG_ROTATION_DIRTY (1 << 1)
+
+/**
+ * Column 3 of localTransform is stale. Position changed; only the translation
+ * column needs to be written. Does not imply columns 0-2 are stale.
+ */
+#define ENTITY_POSITION_FLAG_POSITION_DIRTY (1 << 2)
+
+/**
+ * worldTransform is stale. Either the local matrix changed or an ancestor
+ * moved; the full parent-chain multiply must be rerun before world data is read.
+ */
+#define ENTITY_POSITION_FLAG_WORLD_DIRTY (1 << 3)
+
 typedef struct {
-  mat4 localTransform;
+  /*
-  mat4 worldTransform;
+   * Hot fields — flag checks and parent/child traversal (markDirty, ensureWorld)
-  vec3 position;
+   * only touch these. Kept at the front so they share the first cache line.
-  vec3 rotation;
+   */
-  vec3 scale;
+
-  bool dirty;
+  /** Bitmask of ENTITY_POSITION_FLAG_* values describing which caches are stale. */
+  uint8_t flags;
+  /** Entity ID of the parent node, or ENTITY_ID_INVALID if none. */
   entityid_t parentEntityId;
+  /** Component ID of the parent position component, or COMPONENT_ID_INVALID if none. */
   componentid_t parentComponentId;
+  /** Number of currently registered children. */
   uint8_t childCount;
+  /** Entity IDs of child nodes. */
   entityid_t childEntityIds[ENTITY_POSITION_CHILDREN_MAX];
+  /** Component IDs of child position components. */
   componentid_t childComponentIds[ENTITY_POSITION_CHILDREN_MAX];
+
+  /*
+   * Warm fields — read/written by PRS getters/setters.
+   * Accessed more often than the matrices but less often than flags.
+   */
+
+  /** Cached local position (XYZ). May be stale when ENTITY_POSITION_FLAG_PRS_DIRTY is set. */
+  vec3 position;
+  /** Cached local euler rotation (XYZ, radians). May be stale when ENTITY_POSITION_FLAG_PRS_DIRTY is set. */
+  vec3 rotation;
+  /** Cached local scale (XYZ). May be stale when ENTITY_POSITION_FLAG_PRS_DIRTY is set. */
+  vec3 scale;
+
+  /*
+   * Cold fields — only touched when actually rebuilding transforms.
+   */
+
+  /** Local transform matrix, rebuilt lazily from position/rotation/scale. */
+  mat4 localTransform;
+  /** World transform matrix, recomputed lazily from the parent chain. */
+  mat4 worldTransform;
 } entityposition_t;
 
 /**
- * Initialize the entity position component.
+ * Initializes the entity position component, setting identity transforms and
+ * zeroing all parent/child state.
+ *
+ * @param entityId The entity ID.
+ * @param componentId The component ID.
  */
 void entityPositionInit(
   const entityid_t entityId,
@@ -35,26 +92,26 @@ void entityPositionInit(
 /**
  * Transforms the entity's local transform to look at a target point.
  *
- * @param entityId    The entity ID.
+ * @param entityId The entity ID.
  * @param componentId The component ID.
- * @param target      The target point to look at.
+ * @param eye The eye/camera position.
- * @param up          The up vector.
+ * @param target The target point to look at.
- * @param eye         The eye/camera position.
+ * @param up The up vector.
  */
 void entityPositionLookAt(
   const entityid_t entityId,
   const componentid_t componentId,
+  vec3 eye,
   vec3 target,
-  vec3 up,
+  vec3 up
-  vec3 eye
 );
 
 /**
  * Gets the world-space transform matrix, recomputing it lazily if dirty.
  *
- * @param entityId    The entity ID.
+ * @param entityId The entity ID.
  * @param componentId The component ID.
- * @param dest        Destination matrix.
+ * @param dest Destination matrix.
  */
 void entityPositionGetTransform(
   const entityid_t entityId,
@@ -65,9 +122,9 @@ void entityPositionGetTransform(
 /**
  * Gets the local transform matrix (does not include parent transforms).
  *
- * @param entityId    The entity ID.
+ * @param entityId The entity ID.
  * @param componentId The component ID.
- * @param dest        Destination matrix.
+ * @param dest Destination matrix.
  */
 void entityPositionGetLocalTransform(
   const entityid_t entityId,
@@ -76,54 +133,171 @@ void entityPositionGetLocalTransform(
 );
 
 /**
- * Gets the cached local position.
+ * Gets the cached local position (XYZ). Decomposes localTransform into PRS
+ * first if ENTITY_POSITION_FLAG_PRS_DIRTY is set; never triggers a matrix
+ * rebuild or world-transform update.
+ *
+ * @param entityId The entity ID.
+ * @param componentId The component ID.
+ * @param dest Destination vector.
  */
-void entityPositionGetPosition(
+void entityPositionGetLocalPosition(
   const entityid_t entityId,
   const componentid_t componentId,
   vec3 dest
 );
 
 /**
- * Sets the local position and marks the world transform dirty.
+ * Gets the world-space position. For parentless entities this is the same as
+ * the local position.
+ *
+ * @param entityId The entity ID.
+ * @param componentId The component ID.
+ * @param dest Destination vector.
  */
-void entityPositionSetPosition(
+void entityPositionGetWorldPosition(
+  const entityid_t entityId,
+  const componentid_t componentId,
+  vec3 dest
+);
+
+/**
+ * Sets the world-space position. For parentless entities this is equivalent to
+ * entityPositionSetLocalPosition. For parented entities the position is
+ * converted to local space via the inverted parent world transform.
+ *
+ * @param entityId The entity ID.
+ * @param componentId The component ID.
+ * @param position The desired world-space position.
+ */
+void entityPositionSetWorldPosition(
   const entityid_t entityId,
   const componentid_t componentId,
   vec3 position
 );
 
 /**
- * Gets the cached local euler rotation (XYZ, radians).
+ * Sets the local position, marks localTransform and worldTransform (self +
+ * descendants) dirty.
+ *
+ * @param entityId The entity ID.
+ * @param componentId The component ID.
+ * @param position The new local position.
  */
-void entityPositionGetRotation(
+void entityPositionSetLocalPosition(
+  const entityid_t entityId,
+  const componentid_t componentId,
+  vec3 position
+);
+
+/**
+ * Gets the cached local euler rotation (XYZ, radians). Decomposes
+ * localTransform first if ENTITY_POSITION_FLAG_PRS_DIRTY is set.
+ *
+ * @param entityId The entity ID.
+ * @param componentId The component ID.
+ * @param dest Destination vector.
+ */
+void entityPositionGetLocalRotation(
   const entityid_t entityId,
   const componentid_t componentId,
   vec3 dest
 );
 
 /**
- * Sets the local euler rotation (XYZ, radians) and marks the world transform dirty.
+ * Gets the world-space euler rotation (XYZ, radians) by decomposing the world
+ * transform. For parentless entities this is the same as local rotation.
+ *
+ * @param entityId The entity ID.
+ * @param componentId The component ID.
+ * @param dest Destination vector.
  */
-void entityPositionSetRotation(
+void entityPositionGetWorldRotation(
+  const entityid_t entityId,
+  const componentid_t componentId,
+  vec3 dest
+);
+
+/**
+ * Sets the local euler rotation (XYZ, radians) and marks transforms dirty.
+ *
+ * @param entityId The entity ID.
+ * @param componentId The component ID.
+ * @param rotation The new local rotation.
+ */
+void entityPositionSetLocalRotation(
   const entityid_t entityId,
   const componentid_t componentId,
   vec3 rotation
 );
 
 /**
- * Gets the cached local scale.
+ * Sets the world-space euler rotation (XYZ, radians). For parentless entities
+ * this is equivalent to entityPositionSetLocalRotation. For parented entities
+ * the rotation is converted to local space by removing the parent world
+ * rotation.
+ *
+ * @param entityId The entity ID.
+ * @param componentId The component ID.
+ * @param rotation The desired world-space euler rotation.
  */
-void entityPositionGetScale(
+void entityPositionSetWorldRotation(
+  const entityid_t entityId,
+  const componentid_t componentId,
+  vec3 rotation
+);
+
+/**
+ * Gets the cached local scale. Decomposes localTransform first if
+ * ENTITY_POSITION_FLAG_PRS_DIRTY is set.
+ *
+ * @param entityId The entity ID.
+ * @param componentId The component ID.
+ * @param dest Destination vector.
+ */
+void entityPositionGetLocalScale(
   const entityid_t entityId,
   const componentid_t componentId,
   vec3 dest
 );
 
 /**
- * Sets the local scale and marks the world transform dirty.
+ * Gets the world-space scale by extracting column lengths from the world
+ * transform. For parentless entities this is the same as local scale.
+ *
+ * @param entityId The entity ID.
+ * @param componentId The component ID.
+ * @param dest Destination vector.
  */
-void entityPositionSetScale(
+void entityPositionGetWorldScale(
+  const entityid_t entityId,
+  const componentid_t componentId,
+  vec3 dest
+);
+
+/**
+ * Sets the local scale and marks transforms dirty.
+ *
+ * @param entityId The entity ID.
+ * @param componentId The component ID.
+ * @param scale The new local scale.
+ */
+void entityPositionSetLocalScale(
+  const entityid_t entityId,
+  const componentid_t componentId,
+  vec3 scale
+);
+
+/**
+ * Sets the world-space scale. For parentless entities this is equivalent to
+ * entityPositionSetLocalScale. For parented entities the scale is converted to
+ * local space by dividing by the parent world scale (assumes no shear).
+ *
+ * @param entityId The entity ID.
+ * @param componentId The component ID.
+ * @param scale The desired world-space scale.
+ */
+void entityPositionSetWorldScale(
   const entityid_t entityId,
   const componentid_t componentId,
   vec3 scale
@@ -133,9 +307,9 @@ void entityPositionSetScale(
  * Sets the parent of this entity's position component.
  * Pass ENTITY_ID_INVALID / COMPONENT_ID_INVALID to detach from any parent.
  *
- * @param entityId          The child entity ID.
+ * @param entityId The child entity ID.
- * @param componentId       The child component ID.
+ * @param componentId The child component ID.
- * @param parentEntityId    The parent entity ID.
+ * @param parentEntityId The parent entity ID.
  * @param parentComponentId The parent component ID.
  */
 void entityPositionSetParent(
@@ -147,7 +321,13 @@ void entityPositionSetParent(
 
 /**
  * Returns a direct pointer to the entity position component data.
- * After modifying localTransform directly, call entityPositionMarkDirty().
+ * After modifying localTransform directly, call entityPositionMarkDirty() to
+ * set ENTITY_POSITION_FLAG_WORLD_DIRTY on self and descendants. After
+ * modifying PRS directly, call entityPositionRebuild() instead.
+ *
+ * @param entityId The entity ID.
+ * @param componentId The component ID.
+ * @return Pointer to the component data.
  */
 entityposition_t *entityPositionGet(
   const entityid_t entityId,
@@ -155,13 +335,22 @@ entityposition_t *entityPositionGet(
 );
 
 /**
- * Rebuilds the local transform matrix from the cached position/rotation/scale,
+ * Signals that the PRS cache was modified externally. Sets both
- * then marks this node and all descendants dirty.
+ * ENTITY_POSITION_FLAG_ROTATION_DIRTY and ENTITY_POSITION_FLAG_POSITION_DIRTY
+ * so all of localTransform is rebuilt lazily on the next read, clears
+ * ENTITY_POSITION_FLAG_PRS_DIRTY, and propagates ENTITY_POSITION_FLAG_WORLD_DIRTY
+ * to self and all descendants.
+ *
+ * @param pos The position component whose PRS was modified.
  */
 void entityPositionRebuild(entityposition_t *pos);
 
 /**
- * Marks this node and all descendants as having a stale world transform.
+ * Sets ENTITY_POSITION_FLAG_WORLD_DIRTY on this node and all descendants,
+ * indicating that worldTransform must be recomputed before it is read.
+ * Call this after modifying localTransform directly.
+ *
+ * @param pos The position component to mark dirty.
  */
 void entityPositionMarkDirty(entityposition_t *pos);
 
@@ -169,7 +358,7 @@ void entityPositionMarkDirty(entityposition_t *pos);
  * Disposes this entity and all of its position-component descendants
  * recursively. Detaches from any parent before destroying.
  *
- * @param entityId    The root entity ID.
+ * @param entityId The root entity ID.
  * @param componentId The root position component ID.
  */
 void entityPositionDisposeDeep(
@@ -180,5 +369,7 @@ void entityPositionDisposeDeep(
 /**
  * Decomposes the local transform matrix back into the position, rotation
  * (XYZ euler, radians), and scale cache fields.
+ *
+ * @param pos The position component to decompose.
  */
 void entityPositionDecompose(entityposition_t *pos);

src/dusk/entity/component/display/entityrenderable.c

@@ -7,8 +7,12 @@
 
 #include "entityrenderable.h"
 #include "entity/entitymanager.h"
+#include "display/shader/shadermaterial.h"
 #include "display/shader/shaderunlit.h"
+#include "display/display.h"
 #include "display/mesh/cube.h"
+#include "util/memory.h"
+#include "assert/assert.h"
 
 void entityRenderableInit(
   const entityid_t entityId,
@@ -17,20 +21,22 @@ void entityRenderableInit(
   entityrenderable_t *r = componentGetData(
     entityId, componentId, COMPONENT_TYPE_RENDERABLE
   );
-  r->type = ENTITY_RENDERABLE_TYPE_MATERIAL;
+  memoryZero(r, sizeof(entityrenderable_t));
-  r->mesh = &CUBE_MESH_SIMPLE;
+  r->type = ENTITY_RENDERABLE_TYPE_SHADER_MATERIAL;
-  r->shader = &SHADER_UNLIT;
+  r->data.material.shaderType = SHADER_LIST_SHADER_UNLIT;
-  r->material.unlit.color = COLOR_WHITE;
+  r->data.material.material.unlit.color = COLOR_WHITE;
+  r->data.material.meshes[0] = &CUBE_MESH_SIMPLE;
+  r->data.material.meshOffsets[0] = 0;
+  r->data.material.meshCounts[0] = -1;
+  r->data.material.meshCount = 1;
+  r->data.material.state.flags = DISPLAY_STATE_FLAG_DEPTH_TEST;
 }
 
-entityrenderabletype_t entityRenderableGetType(
+void entityRenderableDispose(
   const entityid_t entityId,
   const componentid_t componentId
 ) {
-  entityrenderable_t *r = componentGetData(
+  
-    entityId, componentId, COMPONENT_TYPE_RENDERABLE
-  );
-  return r->type;
 }
 
 void entityRenderableSetType(
@@ -44,106 +50,79 @@ void entityRenderableSetType(
   r->type = type;
 }
 
-mesh_t * entityRenderableGetMesh(
+void entityRenderableSetPriority(
-  const entityid_t entityId,
-  const componentid_t componentId
-) {
-  entityrenderable_t *r = componentGetData(
-    entityId, componentId, COMPONENT_TYPE_RENDERABLE
-  );
-  return r->mesh;
-}
-
-void entityRenderableSetMesh(
   const entityid_t entityId,
   const componentid_t componentId,
-  mesh_t *mesh
+  const int8_t priority
 ) {
   entityrenderable_t *r = componentGetData(
     entityId, componentId, COMPONENT_TYPE_RENDERABLE
   );
-  r->mesh = mesh;
+  r->priority = priority;
 }
 
-shader_t * entityRenderableGetShader(
+void entityRenderableSetDraw(
-  const entityid_t entityId,
-  const componentid_t componentId
-) {
-  entityrenderable_t *r = componentGetData(
-    entityId, componentId, COMPONENT_TYPE_RENDERABLE
-  );
-  return r->shader;
-}
-
-void entityRenderableSetShader(
   const entityid_t entityId,
   const componentid_t componentId,
-  shader_t *shader
+  errorret_t (*draw)(
+    const entityid_t entityId,
+    const componentid_t componentId,
+    void *user
+  ),
+  void *user
 ) {
+  assertNotNull(draw, "Draw callback cannot be null");
   entityrenderable_t *r = componentGetData(
     entityId, componentId, COMPONENT_TYPE_RENDERABLE
   );
-  r->shader = shader;
+  r->type = ENTITY_RENDERABLE_TYPE_CUSTOM;
+  r->data.custom.draw = draw;
+  r->data.custom.drawUser = user;
 }
 
-shadermaterial_t * entityRenderableGetShaderMaterial(
+errorret_t entityRenderableDraw(
   const entityid_t entityId,
   const componentid_t componentId
 ) {
   entityrenderable_t *r = componentGetData(
     entityId, componentId, COMPONENT_TYPE_RENDERABLE
   );
-  return &r->material;
-}
 
-void entityRenderableSetColor(
+  switch(r->type) {
-  const entityid_t entityId,
+    case ENTITY_RENDERABLE_TYPE_SPRITEBATCH: {
-  const componentid_t componentId,
+      const entityrenderablespritebatch_t *sb = &r->data.spritebatch;
-  const color_t color
+      errorChain(displaySetState((displaystate_t){
-) {
+        .flags = DISPLAY_STATE_FLAG_BLEND
-  entityrenderable_t *r = componentGetData(
+      }));
-    entityId, componentId, COMPONENT_TYPE_RENDERABLE
+      spriteBatchClear();
-  );
+      shadermaterial_t mat;
-  r->material.unlit.color = color;
+      memoryZero(&mat, sizeof(shadermaterial_t));
-}
+      mat.unlit.texture = sb->texture;
+      mat.unlit.color = COLOR_WHITE;
+      errorChain(spriteBatchBuffer(
+        sb->sprites, sb->spriteCount,
+        SHADER_LIST_DEFS[SHADER_LIST_SHADER_UNLIT].shader, mat
+      ));
+      return spriteBatchFlush();
+    }
 
-void entityRenderableSpriteBatchAdd(
+    case ENTITY_RENDERABLE_TYPE_SHADER_MATERIAL: {
-  const entityid_t entityId,
+      const entityrenderablematerial_t *m = &r->data.material;
-  const componentid_t componentId,
+      errorChain(displaySetState(m->state));
-  const spritebatchsprite_t *sprite
+      shader_t *shader = SHADER_LIST_DEFS[m->shaderType].shader;
-) {
+      assertNotNull(shader, "Shader cannot be null for material type");
-  entityrenderable_t *r = componentGetData(
+      errorChain(shaderBind(shader));
-    entityId, componentId, COMPONENT_TYPE_RENDERABLE
+      errorChain(shaderSetMaterial(shader, &m->material));
-  );
+      for(uint8_t i = 0; i < m->meshCount; i++) {
-  if(r->spritebatch.spriteCount >= ENTITY_RENDERABLE_SPRITEBATCH_SPRITES_MAX) return;
+        errorChain(meshDraw(m->meshes[i], m->meshOffsets[i], m->meshCounts[i]));
-  r->spritebatch.sprites[r->spritebatch.spriteCount++] = *sprite;
+      }
-}
+      errorOk();
+    }
 
-void entityRenderableSpriteBatchClear(
+    case ENTITY_RENDERABLE_TYPE_CUSTOM:
-  const entityid_t entityId,
+      return r->data.custom.draw(entityId, componentId, r->data.custom.drawUser);
-  const componentid_t componentId
-) {
-  entityrenderable_t *r = componentGetData(
-    entityId, componentId, COMPONENT_TYPE_RENDERABLE
-  );
-  r->spritebatch.spriteCount = 0;
-}
     
-void entityRenderableDispose(
+    default:
-  const entityid_t entityId,
+      assertUnreachable("Invalid renderable type");
-  const componentid_t componentId
-) {
-  entityrenderable_t *r = componentGetData(
-    entityId, componentId, COMPONENT_TYPE_RENDERABLE
-  );
-  if(
-    r->type == ENTITY_RENDERABLE_TYPE_CALLBACK &&
-    r->userFree &&
-    r->user
-  ) {
-    r->userFree(r->user);
-    r->user = NULL;
   }
-  r->mesh = NULL;
-  r->shader = NULL;
 }

src/dusk/entity/component/display/entityrenderable.h

@@ -10,49 +10,66 @@
 #include "display/mesh/mesh.h"
 #include "display/shader/shadermaterial.h"
 #include "display/spritebatch/spritebatch.h"
+#include "display/displaystate.h"
 
 #define ENTITY_RENDERABLE_SPRITEBATCH_SPRITES_MAX 64
+#define ENTITY_RENDERABLE_MESHES_MAX 8
 
 typedef enum {
-  ENTITY_RENDERABLE_TYPE_MATERIAL = 0,
+  ENTITY_RENDERABLE_TYPE_CUSTOM = 0,
   ENTITY_RENDERABLE_TYPE_SPRITEBATCH,
-  ENTITY_RENDERABLE_TYPE_CALLBACK,
+  ENTITY_RENDERABLE_TYPE_SHADER_MATERIAL,
 } entityrenderabletype_t;
 
-typedef errorret_t (*entityrenderablecallback_t)(
-  const entityid_t entityId,
-  const componentid_t componentId,
-  const mat4 view,
-  const mat4 proj,
-  const mat4 model,
-  void *user
-);
-
 typedef struct {
   spritebatchsprite_t sprites[ENTITY_RENDERABLE_SPRITEBATCH_SPRITES_MAX];
-  uint16_t spriteCount;
+  uint32_t spriteCount;
+  texture_t *texture;
 } entityrenderablespritebatch_t;
 
+typedef struct {
+  mesh_t *meshes[ENTITY_RENDERABLE_MESHES_MAX];
+  int32_t meshOffsets[ENTITY_RENDERABLE_MESHES_MAX];
+  int32_t meshCounts[ENTITY_RENDERABLE_MESHES_MAX];
+  uint8_t meshCount;
+  shaderlistshader_t shaderType;
+  shadermaterial_t material;
+  displaystate_t state;
+} entityrenderablematerial_t;
+
+typedef struct {
+  errorret_t (*draw)(
+    const entityid_t entityId,
+    const componentid_t componentId,
+    void *user
+  );
+  void *drawUser;
+} entityrenderablecustom_t;
+
+typedef union entityrenderabledata_u {
+  entityrenderablespritebatch_t spritebatch;
+  entityrenderablematerial_t material;
+  entityrenderablecustom_t custom;
+} entityrenderabledata_t;
+
 typedef struct {
   entityrenderabletype_t type;
-  shader_t *shader;
+  entityrenderabledata_t data;
-  union {
+  
-    struct {
+  /**
-      mesh_t *mesh;
+   * Render priority. 0 = auto (derived from type/flags). Higher values render
-      shadermaterial_t material;
+   * later (on top of lower values). Range: [-128..127] with 0 is auto.
-    };
+   */
-    entityrenderablespritebatch_t spritebatch;
+  int8_t priority;
-    struct {
-      entityrenderablecallback_t callback;
-      void (*userFree)(void *user);
-      void *user;
-    };
-  };
 } entityrenderable_t;
 
 /**
  * Initializes the entity renderable component. Defaults to
- * ENTITY_RENDERABLE_TYPE_MATERIAL, the unlit shader, white color, no mesh.
+ * ENTITY_RENDERABLE_TYPE_SHADER_MATERIAL with the unlit shader, a white cube,
+ * and depth-test enabled.
+ *
+ * @param entityId The entity to initialize the component for.
+ * @param componentId The renderable component of the entity.
  */
 void entityRenderableInit(
   const entityid_t entityId,
@@ -60,7 +77,10 @@ void entityRenderableInit(
 );
 
 /**
- * Disposes the entity renderable component, freeing any callback user data.
+ * Disposes the entity renderable component.
+ *
+ * @param entityId The entity to dispose the component for.
+ * @param componentId The renderable component of the entity.
  */
 void entityRenderableDispose(
   const entityid_t entityId,
@@ -68,15 +88,12 @@ void entityRenderableDispose(
 );
 
 /**
- * Gets the renderable type.
+ * Sets the rendering type for the renderable component. Resets type-specific
- */
+ * data to zero.
-entityrenderabletype_t entityRenderableGetType(
+ *
-  const entityid_t entityId,
+ * @param entityId The entity to configure.
-  const componentid_t componentId
+ * @param componentId The renderable component.
-);
+ * @param type The rendering type to use.
-
-/**
- * Sets the renderable type.
  */
 void entityRenderableSetType(
   const entityid_t entityId,
@@ -85,73 +102,46 @@ void entityRenderableSetType(
 );
 
 /**
- * Gets the mesh pointer (ENTITY_RENDERABLE_TYPE_MATERIAL only).
+ * Sets the render priority. 0 = auto (derived from type/flags). Higher values
+ * render later (on top). Use non-zero to force ordering.
+ *
+ * @param entityId The entity to configure.
+ * @param componentId The renderable component.
+ * @param priority The priority value, or 0 for auto.
  */
-mesh_t * entityRenderableGetMesh(
+void entityRenderableSetPriority(
-  const entityid_t entityId,
+  const entityid_t entityId,
-  const componentid_t componentId
+  const componentid_t componentId,
-);
+  const int8_t priority
-
+);
-/**
+
- * Sets the mesh pointer (ENTITY_RENDERABLE_TYPE_MATERIAL only).
+/**
- */
+ * Sets the draw callback, switching the type to ENTITY_RENDERABLE_TYPE_CUSTOM.
-void entityRenderableSetMesh(
+ *
-  const entityid_t entityId,
+ * @param entityId The entity to configure.
-  const componentid_t componentId,
+ * @param componentId The renderable component of the entity.
-  mesh_t *mesh
+ * @param draw The draw callback to assign.
-);
+ * @param user Userdata passed to the callback.
-
+ */
-/**
+void entityRenderableSetDraw(
- * Gets the shader pointer.
+  const entityid_t entityId,
- */
+  const componentid_t componentId,
-shader_t * entityRenderableGetShader(
+  errorret_t (*draw)(
-  const entityid_t entityId,
+    const entityid_t entityId,
-  const componentid_t componentId
+    const componentid_t componentId,
-);
+    void *user
-
+  ),
-/**
+  void *user
- * Sets the shader pointer.
+);
- */
+
-void entityRenderableSetShader(
+/**
-  const entityid_t entityId,
+ * Draws the entity using its renderable component data.
-  const componentid_t componentId,
+ *
-  shader_t *shader
+ * @param entityId The entity to draw.
-);
+ * @param componentId The renderable component of the entity.
-
+ * @return Any error state that happened.
-/**
+ */
- * Gets a pointer to the shader material union
+errorret_t entityRenderableDraw(
- * (ENTITY_RENDERABLE_TYPE_MATERIAL only).
- */
-shadermaterial_t * entityRenderableGetShaderMaterial(
-  const entityid_t entityId,
-  const componentid_t componentId
-);
-
-/**
- * Sets the unlit color (ENTITY_RENDERABLE_TYPE_MATERIAL only).
- */
-void entityRenderableSetColor(
-  const entityid_t entityId,
-  const componentid_t componentId,
-  const color_t color
-);
-
-/**
- * Appends a sprite to the spritebatch renderable
- * (ENTITY_RENDERABLE_TYPE_SPRITEBATCH only).
- * Does nothing if the sprite buffer is full.
- */
-void entityRenderableSpriteBatchAdd(
-  const entityid_t entityId,
-  const componentid_t componentId,
-  const spritebatchsprite_t *sprite
-);
-
-/**
- * Clears all buffered sprites from the spritebatch renderable
- * (ENTITY_RENDERABLE_TYPE_SPRITEBATCH only).
- */
-void entityRenderableSpriteBatchClear(
   const entityid_t entityId,
   const componentid_t componentId
 );

src/dusk/entity/component/overworld/CMakeLists.txt

@@ -0,0 +1,13 @@
+# Copyright (c) 2026 Dominic Masters
+#
+# This software is released under the MIT License.
+# https://opensource.org/licenses/MIT
+
+target_sources(${DUSK_LIBRARY_TARGET_NAME}
+  PUBLIC
+    entityinteractable.c
+    entityoverworld.c
+    entityoverworldcamera.c
+    entityoverworldtrigger.c
+    entityplayer.c
+)

src/dusk/entity/component/overworld/entityinteractable.c

@@ -0,0 +1,49 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#include "entityinteractable.h"
+#include "entity/entitymanager.h"
+
+void entityInteractableInit(
+  const entityid_t entityId,
+  const componentid_t componentId
+) {
+  entityinteractable_t *inter = entityInteractableGet(entityId, componentId);
+  inter->onInteract = NULL;
+  inter->user = NULL;
+}
+
+entityinteractable_t * entityInteractableGet(
+  const entityid_t entityId,
+  const componentid_t componentId
+) {
+  return componentGetData(entityId, componentId, COMPONENT_TYPE_INTERACTABLE);
+}
+
+void entityInteractableSetCallback(
+  const entityid_t entityId,
+  const componentid_t componentId,
+  void (*onInteract)(
+    const entityid_t entityId,
+    const componentid_t componentId,
+    void *user
+  ),
+  void *user
+) {
+  entityinteractable_t *inter = entityInteractableGet(entityId, componentId);
+  inter->onInteract = onInteract;
+  inter->user = user;
+}
+
+void entityInteractableTrigger(
+  const entityid_t entityId,
+  const componentid_t componentId
+) {
+  entityinteractable_t *inter = entityInteractableGet(entityId, componentId);
+  if(inter->onInteract == NULL) return;
+  inter->onInteract(entityId, componentId, inter->user);
+}

src/dusk/entity/component/overworld/entityinteractable.h

@@ -0,0 +1,71 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#pragma once
+#include "entity/entitybase.h"
+
+typedef struct {
+  void (*onInteract)(
+    const entityid_t entityId,
+    const componentid_t componentId,
+    void *user
+  );
+  void *user;
+} entityinteractable_t;
+
+/**
+ * Initializes the interactable component, clearing the callback and user pointer.
+ *
+ * @param entityId    The owning entity.
+ * @param componentId This component's ID.
+ */
+void entityInteractableInit(
+  const entityid_t entityId,
+  const componentid_t componentId
+);
+
+/**
+ * Returns a pointer to the interactable component data.
+ *
+ * @param entityId    The owning entity.
+ * @param componentId This component's ID.
+ * @return Pointer to the entityinteractable_t data.
+ */
+entityinteractable_t * entityInteractableGet(
+  const entityid_t entityId,
+  const componentid_t componentId
+);
+
+/**
+ * Sets the callback invoked when this interactable is triggered.
+ *
+ * @param entityId    The owning entity.
+ * @param componentId This component's ID.
+ * @param onInteract  Function called on interaction, or NULL to clear.
+ * @param user        Arbitrary pointer forwarded to the callback.
+ */
+void entityInteractableSetCallback(
+  const entityid_t entityId,
+  const componentid_t componentId,
+  void (*onInteract)(
+    const entityid_t entityId,
+    const componentid_t componentId,
+    void *user
+  ),
+  void *user
+);
+
+/**
+ * Fires the interactable's callback if one is set.
+ *
+ * @param entityId    The owning entity.
+ * @param componentId This component's ID.
+ */
+void entityInteractableTrigger(
+  const entityid_t entityId,
+  const componentid_t componentId
+);

src/dusk/entity/component/overworld/entityoverworld.c

@@ -0,0 +1,55 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#include "entityoverworld.h"
+#include "entity/entitymanager.h"
+#include "entity/component/display/entityrenderable.h"
+#include "display/shader/shaderunlit.h"
+#include "display/mesh/cube.h"
+
+void entityOverworldInit(
+  const entityid_t entityId,
+  const componentid_t componentId
+) {
+  entityoverworld_t *ow = entityOverworldGet(entityId, componentId);
+  ow->type = OVERWORLD_ENTITY_TYPE_NPC;
+  ow->facing = FACING_DIR_DOWN;
+  ow->renderCompId = entityGetComponent(entityId, COMPONENT_TYPE_RENDERABLE);
+  if(ow->renderCompId != COMPONENT_ID_INVALID) {
+    entityRenderableSetDraw(entityId, ow->renderCompId, entityOverworldDraw, NULL);
+  }
+  ow->physCompId = entityGetComponent(entityId, COMPONENT_TYPE_PHYSICS);
+}
+
+entityoverworld_t * entityOverworldGet(
+  const entityid_t entityId,
+  const componentid_t componentId
+) {
+  return componentGetData(entityId, componentId, COMPONENT_TYPE_OVERWORLD);
+}
+
+void entityOverworldSetType(
+  const entityid_t entityId,
+  const componentid_t componentId,
+  const entityoverworldtype_t type
+) {
+  entityOverworldGet(entityId, componentId)->type = type;
+}
+
+errorret_t entityOverworldDraw(
+  const entityid_t entityId,
+  const componentid_t componentId,
+  void *user
+) {
+  componentid_t owCompId = entityGetComponent(entityId, COMPONENT_TYPE_OVERWORLD);
+  entityoverworld_t *ow = entityOverworldGet(entityId, owCompId);
+
+  color_t col = ow->type == OVERWORLD_ENTITY_TYPE_PLAYER ? COLOR_WHITE : COLOR_BLUE;
+  errorChain(shaderSetColor(&SHADER_UNLIT, SHADER_UNLIT_COLOR, col));
+  errorChain(shaderSetTexture(&SHADER_UNLIT, SHADER_UNLIT_TEXTURE, NULL));
+  return meshDraw(&CUBE_MESH_SIMPLE, 0, -1);
+}

src/dusk/entity/component/overworld/entityoverworld.h

@@ -0,0 +1,74 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#pragma once
+#include "error/error.h"
+#include "entity/entitybase.h"
+#include "overworld/facingdir.h"
+
+typedef enum {
+  OVERWORLD_ENTITY_TYPE_PLAYER = 0,
+  OVERWORLD_ENTITY_TYPE_NPC    = 1,
+} entityoverworldtype_t;
+
+typedef struct {
+  entityoverworldtype_t type;
+  facingdir_t facing;
+  componentid_t renderCompId;
+  componentid_t physCompId;
+} entityoverworld_t;
+
+/**
+ * Initializes the overworld component, wiring up the draw callback if a
+ * renderable component is already present on the entity.
+ *
+ * @param entityId    The owning entity.
+ * @param componentId This component's ID.
+ */
+void entityOverworldInit(
+  const entityid_t entityId,
+  const componentid_t componentId
+);
+
+/**
+ * Returns a pointer to the overworld component data.
+ *
+ * @param entityId    The owning entity.
+ * @param componentId This component's ID.
+ * @return Pointer to the entityoverworld_t data.
+ */
+entityoverworld_t * entityOverworldGet(
+  const entityid_t entityId,
+  const componentid_t componentId
+);
+
+/**
+ * Sets the overworld entity type.
+ *
+ * @param entityId    The owning entity.
+ * @param componentId This component's ID.
+ * @param type        The type to assign.
+ */
+void entityOverworldSetType(
+  const entityid_t entityId,
+  const componentid_t componentId,
+  const entityoverworldtype_t type
+);
+
+/**
+ * Draw callback registered on the renderable component.
+ *
+ * @param entityId    The owning entity.
+ * @param componentId The renderable component's ID.
+ * @param user        Unused.
+ * @return Error result.
+ */
+errorret_t entityOverworldDraw(
+  const entityid_t entityId,
+  const componentid_t componentId,
+  void *user
+);

src/dusk/entity/component/overworld/entityoverworldcamera.c

@@ -0,0 +1,66 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#include "entityoverworldcamera.h"
+#include "entity/entitymanager.h"
+#include "entity/component/display/entityposition.h"
+#include "entity/component/display/entitycamera.h"
+
+void entityOverworldCameraInit(
+  const entityid_t entityId,
+  const componentid_t componentId
+) {
+  entityoverworldcamera_t *cam = entityOverworldCameraGet(entityId, componentId);
+  cam->targetEntityId = ENTITY_ID_INVALID;
+  cam->targetPosCompId = COMPONENT_ID_INVALID;
+  glm_vec3_zero(cam->targetOffset);
+  glm_vec3_zero(cam->eyeOffset);
+  cam->scale = 1.0f;
+}
+
+entityoverworldcamera_t * entityOverworldCameraGet(
+  const entityid_t entityId,
+  const componentid_t componentId
+) {
+  return componentGetData(entityId, componentId, COMPONENT_TYPE_OVERWORLD_CAMERA);
+}
+
+void entityOverworldCameraSetTarget(
+  const entityid_t entityId,
+  const componentid_t componentId,
+  const entityid_t targetEntityId,
+  const componentid_t targetPosCompId
+) {
+  entityoverworldcamera_t *cam = entityOverworldCameraGet(entityId, componentId);
+  cam->targetEntityId = targetEntityId;
+  cam->targetPosCompId = targetPosCompId;
+}
+
+errorret_t entityOverworldCameraRender(
+  const entityid_t entityId,
+  const componentid_t componentId
+) {
+  entityoverworldcamera_t *cam = entityOverworldCameraGet(entityId, componentId);
+
+  vec3 targetPos;
+  entityPositionGetWorldPosition(
+    cam->targetEntityId, cam->targetPosCompId, targetPos
+  );
+
+  vec3 center = {
+    targetPos[0] + cam->targetOffset[0],
+    targetPos[1] + cam->targetOffset[1],
+    targetPos[2] + cam->targetOffset[2]
+  };
+
+  componentid_t posComp = entityGetComponent(entityId, COMPONENT_TYPE_POSITION);
+  componentid_t camComp = entityGetComponent(entityId, COMPONENT_TYPE_CAMERA);
+  entityCameraLookAtPixelPerfect(
+    entityId, posComp, camComp, center, cam->eyeOffset, cam->scale
+  );
+  errorOk();
+}

src/dusk/entity/component/overworld/entityoverworldcamera.h

@@ -0,0 +1,69 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#pragma once
+#include "entity/entitybase.h"
+#include "error/error.h"
+
+typedef struct {
+  entityid_t targetEntityId;
+  componentid_t targetPosCompId;
+  vec3 targetOffset;
+  vec3 eyeOffset;
+  float_t scale;
+} entityoverworldcamera_t;
+
+/**
+ * Initializes the overworld camera component.
+ *
+ * @param entityId    The owning entity.
+ * @param componentId This component's ID.
+ */
+void entityOverworldCameraInit(
+  const entityid_t entityId,
+  const componentid_t componentId
+);
+
+/**
+ * Returns a pointer to the overworld camera component data.
+ *
+ * @param entityId    The owning entity.
+ * @param componentId This component's ID.
+ * @return Pointer to the entityoverworldcamera_t data.
+ */
+entityoverworldcamera_t * entityOverworldCameraGet(
+  const entityid_t entityId,
+  const componentid_t componentId
+);
+
+/**
+ * Sets the entity and position component the camera will follow.
+ *
+ * @param entityId        The owning entity.
+ * @param componentId     This component's ID.
+ * @param targetEntityId  Entity to follow.
+ * @param targetPosCompId Position component on the target entity.
+ */
+void entityOverworldCameraSetTarget(
+  const entityid_t entityId,
+  const componentid_t componentId,
+  const entityid_t targetEntityId,
+  const componentid_t targetPosCompId
+);
+
+/**
+ * Render callback: updates the camera position to track the target entity.
+ * Called automatically each frame via componentRenderAll.
+ *
+ * @param entityId    The owning entity.
+ * @param componentId This component's ID.
+ * @return Error state.
+ */
+errorret_t entityOverworldCameraRender(
+  const entityid_t entityId,
+  const componentid_t componentId
+);

src/dusk/entity/component/overworld/entityoverworldtrigger.c

@@ -0,0 +1,83 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#include "entityoverworldtrigger.h"
+#include "entity/entitymanager.h"
+#include "entity/component/display/entityposition.h"
+
+static void entityOverworldTriggerUpdate(
+  const entityid_t entityId,
+  const componentid_t componentId,
+  void *user
+) {
+  entityoverworldtrigger_t *t = entityOverworldTriggerGet(entityId, componentId);
+
+  // Find the player position.
+  vec3 playerPos;
+  bool_t playerFound = false;
+  for(entityid_t i = 0; i < ENTITY_COUNT_MAX; i++) {
+    if((ENTITY_MANAGER.entities[i].state & ENTITY_STATE_ACTIVE) == 0) continue;
+    if(entityGetComponent(i, COMPONENT_TYPE_PLAYER) == COMPONENT_ID_INVALID) continue;
+    componentid_t posComp = entityGetComponent(i, COMPONENT_TYPE_POSITION);
+    if(posComp == COMPONENT_ID_INVALID) continue;
+    entityPositionGetWorldPosition(i, posComp, playerPos);
+    playerFound = true;
+    break;
+  }
+
+  bool_t wasInside = t->playerInside;
+  bool_t nowInside = playerFound && (
+    playerPos[0] >= t->min[0] && playerPos[0] <= t->max[0] &&
+    playerPos[1] >= t->min[1] && playerPos[1] <= t->max[1] &&
+    playerPos[2] >= t->min[2] && playerPos[2] <= t->max[2]
+  );
+  t->playerInside = nowInside;
+
+  if(nowInside) {
+    if(!wasInside && t->onEnter) t->onEnter(entityId, componentId, t->user);
+    if(t->onStay) t->onStay(entityId, componentId, t->user);
+  } else {
+    if(wasInside && t->onExit) t->onExit(entityId, componentId, t->user);
+    if(t->onOutside) t->onOutside(entityId, componentId, t->user);
+  }
+}
+
+void entityOverworldTriggerInit(
+  const entityid_t entityId,
+  const componentid_t componentId
+) {
+  entityoverworldtrigger_t *t = entityOverworldTriggerGet(entityId, componentId);
+  glm_vec3_zero(t->min);
+  glm_vec3_zero(t->max);
+  t->playerInside = false;
+  t->onEnter = NULL;
+  t->onExit = NULL;
+  t->onStay = NULL;
+  t->onOutside = NULL;
+  t->user = NULL;
+  entityUpdateAdd(entityId, entityOverworldTriggerUpdate, componentId, NULL);
+}
+
+entityoverworldtrigger_t * entityOverworldTriggerGet(
+  const entityid_t entityId,
+  const componentid_t componentId
+) {
+  return componentGetData(
+    entityId, componentId, COMPONENT_TYPE_OVERWORLD_TRIGGER
+  );
+}
+
+void entityOverworldTriggerSetBounds(
+  const entityid_t entityId,
+  const componentid_t componentId,
+  const vec3 min,
+  const vec3 max
+) {
+  entityoverworldtrigger_t *t = entityOverworldTriggerGet(entityId, componentId);
+  glm_vec3_copy((float_t*)min, t->min);
+  glm_vec3_copy((float_t*)max, t->max);
+}

src/dusk/entity/component/overworld/entityoverworldtrigger.h

@@ -0,0 +1,54 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#pragma once
+#include "entity/entitybase.h"
+
+typedef void (*entityoverworldtriggercallback_t)(
+  const entityid_t entityId,
+  const componentid_t componentId,
+  void *user
+);
+
+typedef struct {
+  vec3 min;
+  vec3 max;
+  bool_t playerInside;
+  entityoverworldtriggercallback_t onEnter;
+  entityoverworldtriggercallback_t onExit;
+  entityoverworldtriggercallback_t onStay;
+  entityoverworldtriggercallback_t onOutside;
+  void *user;
+} entityoverworldtrigger_t;
+
+/**
+ * Initializes the overworld trigger component and registers its update
+ * callback with the entity manager. The trigger is entirely self-contained
+ * after init — no scene-level wiring required.
+ */
+void entityOverworldTriggerInit(
+  const entityid_t entityId,
+  const componentid_t componentId
+);
+
+/**
+ * Returns a pointer to the overworld trigger component data.
+ */
+entityoverworldtrigger_t * entityOverworldTriggerGet(
+  const entityid_t entityId,
+  const componentid_t componentId
+);
+
+/**
+ * Sets the trigger AABB bounds.
+ */
+void entityOverworldTriggerSetBounds(
+  const entityid_t entityId,
+  const componentid_t componentId,
+  const vec3 min,
+  const vec3 max
+);

src/dusk/entity/component/overworld/entityplayer.c

@@ -0,0 +1,103 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#include "entityplayer.h"
+#include "entity/entitymanager.h"
+#include "entity/component/display/entityposition.h"
+#include "entity/component/physics/entityphysics.h"
+#include "entity/component/overworld/entityoverworld.h"
+#include "entity/component/overworld/entityinteractable.h"
+#include "input/input.h"
+
+void entityPlayerInit(
+  const entityid_t entityId,
+  const componentid_t componentId
+) {
+  entityplayer_t *player = entityPlayerGet(entityId, componentId);
+  player->speed = ENTITY_PLAYER_SPEED;
+  player->runSpeed = ENTITY_PLAYER_RUN_SPEED;
+}
+
+entityplayer_t * entityPlayerGet(
+  const entityid_t entityId,
+  const componentid_t componentId
+) {
+  return componentGetData(entityId, componentId, COMPONENT_TYPE_PLAYER);
+}
+
+void entityPlayerUpdate(
+  const entityid_t entityId,
+  const componentid_t componentId
+) {
+  entityplayer_t *player = entityPlayerGet(entityId, componentId);
+
+  vec2 dir;
+  inputAngle2D(
+    INPUT_ACTION_LEFT, INPUT_ACTION_RIGHT,
+    INPUT_ACTION_UP,   INPUT_ACTION_DOWN,
+    dir
+  );
+
+  float_t speed = (
+    inputIsDown(INPUT_ACTION_CANCEL) ? player->runSpeed : player->speed
+  );
+
+  componentid_t owCompId = entityGetComponent(entityId, COMPONENT_TYPE_OVERWORLD);
+  entityoverworld_t *ow = entityOverworldGet(entityId, owCompId);
+
+  if(ow && glm_vec2_norm(dir) > 0.0f) {
+    if(fabsf(dir[0]) >= fabsf(dir[1])) {
+      ow->facing = dir[0] > 0.0f ? FACING_DIR_RIGHT : FACING_DIR_LEFT;
+    } else {
+      ow->facing = dir[1] > 0.0f ? FACING_DIR_DOWN : FACING_DIR_UP;
+    }
+  }
+
+  vec3 vel;
+  entityPhysicsGetVelocity(entityId, ow->physCompId, vel);
+  vel[0] = dir[0] * speed;
+  vel[2] = dir[1] * speed;
+  entityPhysicsSetVelocity(entityId, ow->physCompId, vel);
+
+  if(!inputPressed(INPUT_ACTION_ACCEPT)) return;
+
+  vec3 playerPos;
+  componentid_t playerPosCompId = entityGetComponent(entityId, COMPONENT_TYPE_POSITION);
+  if(playerPosCompId == COMPONENT_ID_INVALID) return;
+  entityPositionGetWorldPosition(entityId, playerPosCompId, playerPos);
+
+  vec2 facingDir;
+  facingDirToVec2(ow ? ow->facing : FACING_DIR_DOWN, facingDir);
+
+  for(entityid_t i = 0; i < ENTITY_COUNT_MAX; i++) {
+    if((ENTITY_MANAGER.entities[i].state & ENTITY_STATE_ACTIVE) == 0) continue;
+    if(i == entityId) continue;
+
+    componentid_t interComp = entityGetComponent(i, COMPONENT_TYPE_INTERACTABLE);
+    if(interComp == COMPONENT_ID_INVALID) continue;
+
+    componentid_t posComp = entityGetComponent(i, COMPONENT_TYPE_POSITION);
+    if(posComp == COMPONENT_ID_INVALID) continue;
+
+    vec3 targetPos;
+    entityPositionGetWorldPosition(i, posComp, targetPos);
+
+    vec2 toTarget = {
+      targetPos[0] - playerPos[0],
+      targetPos[2] - playerPos[2],
+    };
+    float_t forward = glm_vec2_dot(facingDir, toTarget);
+    if(forward <= 0.0f || forward > ENTITY_PLAYER_INTERACT_RANGE) continue;
+
+    float_t lateral = fabsf(
+      facingDir[0] * toTarget[1] - facingDir[1] * toTarget[0]
+    );
+    if(lateral > ENTITY_PLAYER_INTERACT_LATERAL) continue;
+
+    entityInteractableTrigger(i, interComp);
+  }
+}

src/dusk/entity/component/overworld/entityplayer.h

@@ -0,0 +1,52 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#pragma once
+#include "error/error.h"
+#include "entity/entitybase.h"
+
+#define ENTITY_PLAYER_SPEED 4.0f
+#define ENTITY_PLAYER_RUN_SPEED 8.0f
+#define ENTITY_PLAYER_INTERACT_RANGE 1.5f
+#define ENTITY_PLAYER_INTERACT_LATERAL 0.6f
+
+typedef struct {
+  float_t speed;
+  float_t runSpeed;
+} entityplayer_t;
+
+/**
+ * Initializes the player component.
+ *
+ * @param entityId    The owning entity.
+ * @param componentId This component's ID.
+ */
+void entityPlayerInit(const entityid_t entityId, const componentid_t componentId);
+
+/**
+ * Returns a pointer to the player component data.
+ *
+ * @param entityId    The owning entity.
+ * @param componentId This component's ID.
+ * @return Pointer to the entityplayer_t data.
+ */
+entityplayer_t * entityPlayerGet(
+  const entityid_t entityId,
+  const componentid_t componentId
+);
+
+/**
+ * Reads input, moves the player, updates facing direction, and checks for
+ * interactable entities in front of the player when accept is pressed.
+ *
+ * @param entityId    The owning entity.
+ * @param componentId This component's ID.
+ */
+void entityPlayerUpdate(
+  const entityid_t entityId,
+  const componentid_t componentId
+);

src/dusk/entity/componentlist.h

@@ -10,15 +10,26 @@
 #include "entity/component/display/entityrenderable.h"
 #include "entity/component/physics/entityphysics.h"
 #include "entity/component/trigger/entitytrigger.h"
+#include "entity/component/overworld/entityoverworld.h"
+#include "entity/component/overworld/entityoverworldtrigger.h"
+#include "entity/component/overworld/entityplayer.h"
+#include "entity/component/overworld/entityinteractable.h"
+#include "entity/component/overworld/entityoverworldcamera.h"
 
 // Name (Uppercase)
 // Structure
 // Field name (lowercase)
 // Init function (optional)
 // Dispose function (optional)
+// Render function (optional)
 
-X(POSITION,   entityposition_t,   position,   entityPositionInit,   NULL)
+X(POSITION, entityposition_t, position, entityPositionInit, NULL, NULL)
-X(CAMERA,     entitycamera_t,     camera,     entityCameraInit,     NULL)
+X(CAMERA, entitycamera_t, camera, entityCameraInit, NULL, NULL)
-X(RENDERABLE, entityrenderable_t, renderable, entityRenderableInit, entityRenderableDispose)
+X(RENDERABLE, entityrenderable_t, renderable, entityRenderableInit, entityRenderableDispose, NULL)
-X(PHYSICS,    entityphysics_t,    physics,    entityPhysicsInit,    entityPhysicsDispose)
+X(PHYSICS, entityphysics_t, physics, entityPhysicsInit, entityPhysicsDispose, NULL)
-X(TRIGGER,    entitytrigger_t,    trigger,    entityTriggerInit,    NULL)
+X(TRIGGER, entitytrigger_t, trigger, entityTriggerInit, NULL, NULL)
+X(OVERWORLD, entityoverworld_t, overworld, entityOverworldInit, NULL, NULL)
+X(PLAYER, entityplayer_t, player, entityPlayerInit, NULL, NULL)
+X(INTERACTABLE, entityinteractable_t, interactable, entityInteractableInit, NULL, NULL)
+X(OVERWORLD_CAMERA, entityoverworldcamera_t, overworldCamera, entityOverworldCameraInit, NULL, entityOverworldCameraRender)
+X(OVERWORLD_TRIGGER, entityoverworldtrigger_t, overworldTrigger, entityOverworldTriggerInit, NULL, NULL)

src/dusk/entity/entity.c

@@ -80,10 +80,21 @@ void entityDisposeDeep(const entityid_t entityId) {
   }
 }
 
+void entityUpdate(const entityid_t entityId) {
+  entity_t *ent = &ENTITY_MANAGER.entities[entityId];
+  for(uint8_t i = 0; i < ent->updateCount; i++) {
+    ent->onUpdate[i](entityId, ent->updateComponentId[i], ent->updateUser[i]);
+  }
+}
+
 void entityDispose(const entityid_t entityId) {
   componentindex_t compInd;
   entity_t *ent = &ENTITY_MANAGER.entities[entityId];
 
+  for(uint8_t i = 0; i < ent->disposeCount; i++) {
+    ent->onDispose[i](entityId, ent->disposeComponentId[i], ent->disposeUser[i]);
+  }
+
   for(componentid_t i = 0; i < ENTITY_COMPONENT_COUNT_MAX; i++) {
     compInd = componentGetIndex(entityId, i);
     componenttype_t type = ENTITY_MANAGER.components[compInd].type;
@@ -96,3 +107,65 @@ void entityDispose(const entityid_t entityId) {
 
   ent->state = 0;
 }
+
+void entityUpdateAdd(
+  const entityid_t entityId,
+  const entitycallback_t callback,
+  const componentid_t componentId,
+  void *user
+) {
+  entity_t *ent = &ENTITY_MANAGER.entities[entityId];
+  assertTrue(
+    ent->updateCount < ENTITY_UPDATE_CALLBACK_COUNT_MAX,
+    "Entity update callback slots full"
+  );
+  ent->onUpdate[ent->updateCount] = callback;
+  ent->updateComponentId[ent->updateCount] = componentId;
+  ent->updateUser[ent->updateCount] = user;
+  ent->updateCount++;
+}
+
+void entityUpdateRemove(const entityid_t entityId, const entitycallback_t callback) {
+  entity_t *ent = &ENTITY_MANAGER.entities[entityId];
+  for(uint8_t i = 0; i < ent->updateCount; i++) {
+    if(ent->onUpdate[i] != callback) continue;
+    ent->updateCount--;
+    for(uint8_t j = i; j < ent->updateCount; j++) {
+      ent->onUpdate[j]        = ent->onUpdate[j + 1];
+      ent->updateComponentId[j] = ent->updateComponentId[j + 1];
+      ent->updateUser[j]      = ent->updateUser[j + 1];
+    }
+    return;
+  }
+}
+
+void entityDisposeAdd(
+  const entityid_t entityId,
+  const entitycallback_t callback,
+  const componentid_t componentId,
+  void *user
+) {
+  entity_t *ent = &ENTITY_MANAGER.entities[entityId];
+  assertTrue(
+    ent->disposeCount < ENTITY_DISPOSE_CALLBACK_COUNT_MAX,
+    "Entity dispose callback slots full"
+  );
+  ent->onDispose[ent->disposeCount] = callback;
+  ent->disposeComponentId[ent->disposeCount] = componentId;
+  ent->disposeUser[ent->disposeCount] = user;
+  ent->disposeCount++;
+}
+
+void entityDisposeRemove(const entityid_t entityId, const entitycallback_t callback) {
+  entity_t *ent = &ENTITY_MANAGER.entities[entityId];
+  for(uint8_t i = 0; i < ent->disposeCount; i++) {
+    if(ent->onDispose[i] != callback) continue;
+    ent->disposeCount--;
+    for(uint8_t j = i; j < ent->disposeCount; j++) {
+      ent->onDispose[j]         = ent->onDispose[j + 1];
+      ent->disposeComponentId[j] = ent->disposeComponentId[j + 1];
+      ent->disposeUser[j]       = ent->disposeUser[j + 1];
+    }
+    return;
+  }
+}

src/dusk/entity/entity.h

@@ -10,8 +10,25 @@
 
 #define ENTITY_STATE_ACTIVE (1 << 0)
 
+#define ENTITY_UPDATE_CALLBACK_COUNT_MAX  5
+#define ENTITY_DISPOSE_CALLBACK_COUNT_MAX 5
+
+typedef void (*entitycallback_t)(
+  const entityid_t entityId,
+  const componentid_t componentId,
+  void *user
+);
+
 typedef struct {
   uint8_t state;
+  uint8_t updateCount;
+  uint8_t disposeCount;
+  entitycallback_t onUpdate[ENTITY_UPDATE_CALLBACK_COUNT_MAX];
+  componentid_t updateComponentId[ENTITY_UPDATE_CALLBACK_COUNT_MAX];
+  void *updateUser[ENTITY_UPDATE_CALLBACK_COUNT_MAX];
+  entitycallback_t onDispose[ENTITY_DISPOSE_CALLBACK_COUNT_MAX];
+  componentid_t disposeComponentId[ENTITY_DISPOSE_CALLBACK_COUNT_MAX];
+  void *disposeUser[ENTITY_DISPOSE_CALLBACK_COUNT_MAX];
 } entity_t;
 
 /**
@@ -47,7 +64,15 @@ componentid_t entityGetComponent(
 );
 
 /**
- * Disposes of an entity with the given ID.
+ * Runs all registered update callbacks for the entity.
+ *
+ * @param entityId The ID of the entity to update.
+ */
+void entityUpdate(const entityid_t entityId);
+
+/**
+ * Disposes of an entity with the given ID. Fires all dispose callbacks before
+ * cleaning up components and state.
  *
  * @param entityId The ID of the entity to dispose of.
  */
@@ -61,3 +86,46 @@ void entityDispose(const entityid_t entityId);
  * @param entityId The root entity ID.
  */
 void entityDisposeDeep(const entityid_t entityId);
+
+/**
+ * Registers an update callback, invoked each time entityUpdate is called.
+ *
+ * @param entityId The entity to register on.
+ * @param callback The function to call.
+ */
+void entityUpdateAdd(
+  const entityid_t entityId,
+  const entitycallback_t callback,
+  const componentid_t componentId,
+  void *user
+);
+
+/**
+ * Removes a previously registered update callback.
+ *
+ * @param entityId The entity to remove from.
+ * @param callback The function to remove.
+ */
+void entityUpdateRemove(const entityid_t entityId, const entitycallback_t callback);
+
+/**
+ * Registers a dispose callback, invoked at the start of entityDispose before
+ * any component or state cleanup.
+ *
+ * @param entityId The entity to register on.
+ * @param callback The function to call.
+ */
+void entityDisposeAdd(
+  const entityid_t entityId,
+  const entitycallback_t callback,
+  const componentid_t componentId,
+  void *user
+);
+
+/**
+ * Removes a previously registered dispose callback.
+ *
+ * @param entityId The entity to remove from.
+ * @param callback The function to remove.
+ */
+void entityDisposeRemove(const entityid_t entityId, const entitycallback_t callback);

src/dusk/entity/entitybase.h

@@ -8,11 +8,11 @@
 #pragma once
 #include "dusk.h"
 
-#define ENTITY_COUNT_MAX 20
+#define ENTITY_COUNT_MAX 64
-#define ENTITY_COMPONENT_COUNT_MAX 8
+#define ENTITY_COMPONENT_COUNT_MAX 16
 
-#define ENTITY_ID_INVALID     0xFF
+#define ENTITY_ID_INVALID 0xFF
-#define COMPONENT_ID_INVALID  0xFF
+#define COMPONENT_ID_INVALID 0xFF
 
 typedef uint8_t entityid_t;
 typedef uint8_t componentid_t;

src/dusk/entity/entitymanager.c

@@ -16,7 +16,7 @@ void entityManagerInit(void) {
   memoryZero(&ENTITY_MANAGER, sizeof(entitymanager_t));
   memorySet(
     ENTITY_MANAGER.entitiesWithComponent, COMPONENT_ID_INVALID,
-    sizeof(entityid_t) * COMPONENT_TYPE_COUNT * ENTITY_COUNT_MAX
+    sizeof(componentid_t) * COMPONENT_TYPE_COUNT * ENTITY_COUNT_MAX
   );
 
   consolePrint(
@@ -36,6 +36,16 @@ entityid_t entityManagerAdd() {
   return ENTITY_ID_INVALID;
 }
 
+void entityManagerUpdate(void) {
+  entityid_t i = 0;
+  while(i < ENTITY_COUNT_MAX) {
+    if((ENTITY_MANAGER.entities[i].state & ENTITY_STATE_ACTIVE) != 0) {
+      entityUpdate(i);
+    }
+    i++;
+  }
+}
+
 void entityManagerDispose(void) {
   for(entityid_t i = 0; i < ENTITY_COUNT_MAX; i++) {
     if((ENTITY_MANAGER.entities[i].state & ENTITY_STATE_ACTIVE) == 0) continue;

src/dusk/entity/entitymanager.h

@@ -28,6 +28,11 @@ void entityManagerInit(void);
  */
 entityid_t entityManagerAdd();
 
+/**
+ * Updates all active entities.
+ */
+void entityManagerUpdate(void);
+
 /**
  * Disposes of the entity manager, in turn freeing all entities and components.
  */

src/dusk/error/error.c

@@ -11,7 +11,7 @@
 #include "util/string.h"
 #include "log/log.h"
 
-errorstate_t ERROR_STATE = { 0 };
+THREAD_LOCAL errorstate_t ERROR_STATE = { 0 };
 
 errorret_t errorThrowImpl(
   errorstate_t *state,
@@ -77,7 +77,7 @@ errorret_t errorChainImpl(
   const char_t *function,
   const int32_t line
 ) {
-  if(retval.code == ERROR_OK) return retval;
+  if(errorIsOk(retval)) return retval;
 
   assertNotNull(retval.state, "Error state NULL (Likely missing errorOk)");
   assertNotNull(retval.state->message, "Message cannot be NULL");
@@ -111,18 +111,19 @@ errorret_t errorChainImpl(
 }
 
 void errorCatch(errorret_t retval) {
-  if(retval.code == ERROR_OK) return;
+  if(errorIsOk(retval)) return;
 
   assertNotNull(retval.state, "Error state cannot be NULL");
   assertNotNull(retval.state->message, "Message cannot be NULL");
 
   // Clear the error state
   memoryFree((void*)retval.state->message);
+  memoryFree((void*)retval.state->lines);
   retval.state->code = ERROR_OK;
 }
 
 errorret_t errorPrint(const errorret_t retval) {
-  if(retval.code == ERROR_OK) return retval;
+  if(errorIsOk(retval)) return retval;
 
   assertNotNull(retval.state, "Error state cannot be NULL");
   assertNotNull(retval.state->message, "Message cannot be NULL");

src/dusk/error/error.h

@@ -7,6 +7,7 @@
 
 #pragma once
 #include "dusk.h"
+#include "thread/threadlocal.h"
 
 typedef uint8_t errorcode_t;
 
@@ -26,7 +27,7 @@ static const errorcode_t ERROR_NOT_OK = 1;
 
 static const char_t *ERROR_PRINT_FORMAT = "Error (%d): %s\n%s";
 static const char_t *ERROR_LINE_FORMAT = "  at %s:%d in function %s\n";
-extern errorstate_t ERROR_STATE;
+extern THREAD_LOCAL errorstate_t ERROR_STATE;
 
 /**
  * Sets the error state with the provided code and message.
@@ -88,34 +89,6 @@ void errorCatch(errorret_t retval);
  */
 errorret_t errorPrint(const errorret_t retval);
 
-/**
- * Creates an error with a specific error state.
- * 
- * @param state The error state to set.
- * @param message The format string for the error message.
- * @param ... Additional arguments for the format string.
- * @return The error code.
- */
-#define errorCreate(state, message, ... ) \
-  errorThrowImpl(\
-    (state), ERROR_NOT_OK, __FILE__, __func__, __LINE__, (message), \
-    ##__VA_ARGS__ \
-  )
-
-/**
- * Throws an error with a specific error state.
- * 
- * @param state The error state to set.
- * @param message The format string for the error message.
- * @param ... Additional arguments for the format string.
- * @return The error code.
- */
-#define errorThrowState(state, message, ... ) \
-  return errorThrowImpl(\
-    (state), ERROR_NOT_OK, __FILE__, __func__, __LINE__, (message), \
-    ##__VA_ARGS__ \
-  )
-
 /**
  * Throws an error with a formatted message.
  * 
@@ -155,11 +128,26 @@ errorret_t errorPrint(const errorret_t retval);
   } \
 }
 
-
 /**
  * Returns without an error.
+ * 
+ * @return An error state with code ERROR_OK.
  */
 #define errorOk() \
   return errorOkImpl()
 
+/**
+ * Returns non-zero if retval indicates success.
+ *
+ * @param retval errorret_t to test.
+ */
+#define errorIsOk(retval) ((retval).code == ERROR_OK)
+
+/**
+ * Returns non-zero if retval indicates failure.
+ *
+ * @param retval errorret_t to test.
+ */
+#define errorIsNotOk(retval) ((retval).code != ERROR_OK)
+
 // EOF

src/dusk/event/event.c

@@ -9,43 +9,53 @@
 #include "assert/assert.h"
 #include "util/memory.h"
 
-void eventInit(event_t *event) {
+void eventInit(event_t *event, eventcallback_t *callbacks, void **users, size_t size) {
   assertNotNull(event, "event must not be NULL");
-  memoryZero(event, sizeof(event_t));
+  assertNotNull((void *)callbacks, "callbacks must not be NULL");
+  assertTrue(size > 0, "size must be greater than 0");
+
+  event->callbacks = callbacks;
+  event->users = users;
+  event->size = size;
+  event->count = 0;
+  memoryZero(callbacks, sizeof(eventcallback_t) * size);
+  if(users) memoryZero(users, sizeof(void *) * size);
 }
 
 void eventSubscribe(event_t *event, eventcallback_t callback, void *user) {
   assertNotNull(event, "event must not be NULL");
-  assertNotNull((void *)callback, "callback must not be NULL");
+  assertNotNull(callback, "callback must not be NULL");
 
-  for(uint8_t i = 0; i < event->count; i++) {
+  // Ensure callback isn't already susbcribed
-    if(event->callbacks[i] == callback && event->users[i] == user) return;
+  for(uint32_t i = 0; i < event->count; i++) {
+    if(event->callbacks[i] != callback) continue;
+    assertUnreachable("Callback already registered, cannot subscribe twice.");
   }
 
-  assertTrue(
+  assertTrue(event->count < event->size, "event subscriber capacity exceeded");
-    event->count < EVENT_SUBSCRIBER_COUNT_MAX,
-    "EVENT_SUBSCRIBER_COUNT_MAX exceeded"
-  );
 
   event->callbacks[event->count] = callback;
-  event->users[event->count] = user;
+  if(user) {
+    assertNotNull(event->users, "Cannot add user pointer.");
+    event->users[event->count] = user;
+  }
   event->count++;
 }
 
-void eventUnsubscribe(event_t *event, eventcallback_t callback, void *user) {
+void eventUnsubscribe(event_t *event, eventcallback_t callback) {
   assertNotNull(event, "event must not be NULL");
-  assertNotNull((void *)callback, "callback must not be NULL");
+  assertNotNull(callback, "callback must not be NULL");
 
-  for(uint8_t i = 0; i < event->count; i++) {
+  for(uint32_t i = 0; i < event->count; i++) {
-    if(event->callbacks[i] != callback || event->users[i] != user) continue;
+    if(event->callbacks[i] != callback) continue;
 
-    uint8_t last = event->count - 1;
+    uint32_t last = event->count - 1;
     if(i != last) {
       event->callbacks[i] = event->callbacks[last];
-      event->users[i] = event->users[last];
+      if(event->users) event->users[i] = event->users[last];
     }
     event->callbacks[last] = NULL;
-    event->users[last] = NULL;
+    if(event->users) event->users[last] = NULL;
     event->count--;
     return;
   }
@@ -53,7 +63,9 @@ void eventUnsubscribe(event_t *event, eventcallback_t callback, void *user) {
 
 void eventInvoke(const event_t *event, void *params) {
   assertNotNull(event, "event must not be NULL");
-  for(uint8_t i = 0; i < event->count; i++) {
+
-    event->callbacks[i](params, event->users[i]);
+  for(uint32_t i = 0; i < event->count; i++) {
+    void *u = event->users ? event->users[i] : NULL;
+    event->callbacks[i](params, u);
   }
 }

src/dusk/event/event.h

@@ -8,31 +8,40 @@
 #pragma once
 #include "dusk.h"
 
-#define EVENT_SUBSCRIBER_COUNT_MAX 8
-
 typedef void (*eventcallback_t)(void *params, void *user);
 
 typedef struct {
-  eventcallback_t callbacks[EVENT_SUBSCRIBER_COUNT_MAX];
+  eventcallback_t *callbacks;
-  void *users[EVENT_SUBSCRIBER_COUNT_MAX];
+  void **users;
-  uint8_t count;
+  size_t size;
+  uint32_t count;
 } event_t;
 
 /**
- * Initializes an event, clearing all subscribers.
+ * Initializes an event, binding it to the provided backing arrays and clearing
+ * all subscribers. May also be called to reset an event (re-clears subscribers
+ * without changing the backing arrays or size).
  *
  * @param event The event to initialize.
+ * @param callbacks Caller-owned array of at least `size` callback slots.
+ * @param users Array of user pointers, matching each callback, or NULL.
+ * @param size Capacity of both arrays, must match.
  */
-void eventInit(event_t *event);
+void eventInit(
+  event_t *event,
+  eventcallback_t *callbacks,
+  void **users,
+  size_t size
+);
 
 /**
  * Subscribes a callback to an event. The callback is invoked with params and
  * the provided user pointer each time the event fires. The same (callback,
  * user) pair may only be subscribed once.
  *
- * @param event    The event to subscribe to.
+ * @param event The event to subscribe to.
  * @param callback The function to call when the event fires.
- * @param user     Arbitrary pointer forwarded to the callback unchanged.
+ * @param user Arbitrary pointer forwarded to the callback unchanged.
  */
 void eventSubscribe(event_t *event, eventcallback_t callback, void *user);
 
@@ -40,17 +49,16 @@ void eventSubscribe(event_t *event, eventcallback_t callback, void *user);
  * Removes a previously subscribed (callback, user) pair. Does nothing if the
  * pair is not currently subscribed.
  *
- * @param event    The event to unsubscribe from.
+ * @param event The event to unsubscribe from.
  * @param callback The callback that was passed to eventSubscribe.
- * @param user     The user pointer that was passed to eventSubscribe.
  */
-void eventUnsubscribe(event_t *event, eventcallback_t callback, void *user);
+void eventUnsubscribe(event_t *event, eventcallback_t callback);
 
 /**
  * Invokes all subscribed callbacks, passing params and each subscriber's user
  * pointer.
  *
- * @param event  The event to invoke.
+ * @param event The event to invoke.
  * @param params Arbitrary pointer forwarded to every callback unchanged.
  */
 void eventInvoke(const event_t *event, void *params);

src/dusk/input/input.c

@@ -22,8 +22,8 @@ errorret_t inputInit(void) {
     INPUT.actions[i].action = (inputaction_t)i;
     INPUT.actions[i].lastValue = 0.0f;
     INPUT.actions[i].currentValue = 0.0f;
-    eventInit(&INPUT.actions[i].onPressed);
+    eventInit(&INPUT.actions[i].onPressed, INPUT.actions[i].onPressedCallbacks, INPUT.actions[i].onPressedUsers, 4);
-    eventInit(&INPUT.actions[i].onReleased);
+    eventInit(&INPUT.actions[i].onReleased, INPUT.actions[i].onReleasedCallbacks, INPUT.actions[i].onReleasedUsers, 4);
   }
 
   #ifdef inputInitPlatform
@@ -162,6 +162,28 @@ void inputAxis2D(
   result[1] = inputAxis(negY, posY);
 }
 
+void inputAngle2D(
+  const inputaction_t negX, const inputaction_t posX,
+  const inputaction_t negY, const inputaction_t posY,
+  vec2 result
+) {
+  assertNotNull(result, "Result vector cannot be null");
+  float_t x = inputAxis(negX, posX);
+  float_t y = inputAxis(negY, posY);
+  float_t mag = sqrtf(x * x + y * y);
+  if(mag <= 0.0f) {
+    result[0] = 0.0f;
+    result[1] = 0.0f;
+    return;
+  }
+  if(mag > 1.0f) {
+    x /= mag;
+    y /= mag;
+  }
+  result[0] = x;
+  result[1] = y;
+}
+
 void inputBind(const inputbutton_t button, const inputaction_t act) {
   assertTrue(
     act < INPUT_ACTION_COUNT,
@@ -177,8 +199,6 @@ void inputBind(const inputbutton_t button, const inputaction_t act) {
   data->action = act;
 }
 
-
-
 float_t inputDeadzone(const float_t rawValue, const float_t deadzone) {
   if(rawValue < deadzone) return 0.0f;
   return (rawValue - deadzone) / (1.0f - deadzone);

src/dusk/input/input.h

@@ -126,6 +126,22 @@ void inputAxis2D(
   vec2 result
 );
 
+/**
+ * Returns an angled 2D vector based on the input of 4 actions. Functionally
+ * using atan2 to get the angle of the input then multiplying by a unit vector.
+ * 
+ * @param negX The action representing the negative direction of the X axis.
+ * @param posX The action representing the positive direction of the X axis.
+ * @param negY The action representing the negative direction of the Y axis.
+ * @param posY The action representing the positive direction of the Y axis.
+ * @param result A vec2 to store the resulting axis values (-1.0f to 1.0f).
+ */
+void inputAngle2D(
+  const inputaction_t negX, const inputaction_t posX,
+  const inputaction_t negY, const inputaction_t posY,
+  vec2 result
+);
+
 /**
  * Binds an input button to an action.
  * 

src/dusk/input/inputaction.h

@@ -20,7 +20,11 @@ typedef struct {
     float_t currentDynamicValue;
   #endif
 
+  eventcallback_t onPressedCallbacks[4];
+  void *onPressedUsers[4];
   event_t onPressed;
+  eventcallback_t onReleasedCallbacks[4];
+  void *onReleasedUsers[4];
   event_t onReleased;
 } inputactiondata_t;
 

src/dusk/locale/localemanager.c

@@ -13,28 +13,31 @@ localemanager_t LOCALE;
 
 errorret_t localeManagerInit() {
   memoryZero(&LOCALE, sizeof(localemanager_t));
-
   errorChain(localeManagerSetLocale(&LOCALE_EN_US));
-
   errorOk();
 }
 
 errorret_t localeManagerSetLocale(const localeinfo_t *locale) {
-  if(LOCALE.fileOpen) {
+  assertNotNull(locale, "Locale cannot be NULL");
-    errorChain(assetLocaleFileDispose(&LOCALE.file));
+
-    LOCALE.fileOpen = false;
+  if(LOCALE.entry != NULL) {
+    assetEntryUnlock(LOCALE.entry);
+    LOCALE.entry = NULL;
   }
 
-  // Init the asset file
+  LOCALE.locale = locale;
-  errorChain(assetLocaleFileInit(&LOCALE.file, locale->file));
+  LOCALE.entry = assetGetEntry(locale->file, ASSET_LOADER_TYPE_LOCALE, NULL);
-  LOCALE.fileOpen = true;
+  assetEntryLock(LOCALE.entry);
+  errorChain(assetRequireLoaded(LOCALE.entry));
 
   errorOk();
 }
 
 void localeManagerDispose() {
-  if(LOCALE.fileOpen) {
+  if(LOCALE.entry != NULL) {
-    errorCatch(errorPrint(assetLocaleFileDispose(&LOCALE.file)));
+    assetEntryUnlock(LOCALE.entry);
-    LOCALE.fileOpen = false;
+    LOCALE.entry = NULL;
   }
+  
+  LOCALE.locale = NULL;
 }

src/dusk/locale/localemanager.h

@@ -9,12 +9,11 @@
 #include "error/error.h"
 #include "localemanager.h"
 #include "locale/localeinfo.h"
-#include "asset/loader/locale/assetlocaleloader.h"
+#include "asset/asset.h"
 
 typedef struct {
   const localeinfo_t *locale;
-  assetlocalefile_t file;
+  assetentry_t *entry;
-  bool_t fileOpen;
 } localemanager_t;
 
 extern localemanager_t LOCALE;
@@ -46,7 +45,7 @@ errorret_t localeManagerSetLocale(const localeinfo_t *locale);
  */
 #define localeManagerGetText(id, buffer, bufferSize, plural, ...) \
   assetLocaleGetStringWithVA( \
-    &LOCALE.file, \
+    &LOCALE.entry->data.locale, \
     id, \
     plural, \
     buffer, \
@@ -69,7 +68,7 @@ errorret_t localeManagerSetLocale(const localeinfo_t *locale);
   id, buffer, bufferSize, plural, args, argCount \
 ) \
   assetLocaleGetStringWithArgs( \
-    &LOCALE.file, \
+    &LOCALE.entry->data.locale, \
     id, \
     plural, \
     buffer, \

src/dusk/main.c

@@ -15,7 +15,7 @@ int main(int argc, char **argv) {
 
   // Init engine
   ret = engineInit(argc, (const char_t **)argv);
-  if(ret.code != ERROR_OK) {
+  if(errorIsNotOk(ret)) {
     errorCatch(errorPrint(ret));
     return ret.code;
   }
@@ -23,14 +23,14 @@ int main(int argc, char **argv) {
   // Begin main loop
   do {
     ret = engineUpdate();
-    if(ret.code != ERROR_OK) {
+    if(errorIsNotOk(ret)) {
       errorCatch(errorPrint(ret));
       return ret.code;
     }
   } while(ENGINE.running);
 
   ret = engineDispose();
-  if(ret.code != ERROR_OK) {
+  if(errorIsNotOk(ret)) {
     errorCatch(errorPrint(ret));
     return ret.code;
   }