Chunks as json

assets/cutscene/test_npc.json

@@ -0,0 +1,25 @@
+{
+  "pause": "DEFAULT",
+  "items": [
+    { "type": "text", "text": "Test Two." },
+    { "type": "entityAdd", "entityType": "npc", "position": [4, 4, 0] },
+    {
+      "type": "textMini",
+      "text": "Hello!",
+      "position": [4, 4, 0],
+      "duration": 3.0
+    },
+    {
+      "type": "emoji",
+      "entityIndex": "lastCreated",
+      "emojiType": "exclamation",
+      "duration": 2.0
+    },
+    {
+      "type": "entityWalkTo",
+      "entityIndex": "lastCreated",
+      "positions": [[8, 2, 0]]
+    },
+    { "type": "text", "text": "Done." }
+  ]
+}

assets/item.json

@@ -0,0 +1,5 @@
+[
+  { "id": "POTION", "type": "MEDICINE", "weight": 1.0, "name": "potion" },
+  { "id": "POTATO", "type": "FOOD", "weight": 0.5, "name": "potato" },
+  { "id": "APPLE", "type": "FOOD", "weight": 0.3, "name": "apple" }
+]

assets/locale/en_US.po

@@ -10,51 +10,57 @@ msgid "ui.title"
 msgstr ""
 "Welcome"
 
-#: ui/user.c:22
-msgid "ui.greeting"
-msgstr "Hello, %s!"
+#: src/dusk/ui/frame/settings/uisettings.c
+msgid "ui.settings.tabs.general"
+msgstr "General"
 
-#: ui/files.c:40
-msgid "ui.file_status"
-msgstr "%s has %d files."
+#: src/dusk/ui/frame/settings/uisettings.c
+msgid "ui.settings.tabs.input"
+msgstr "Input"
 
-#: ui/cart.c:55
-msgid "cart.item_count"
-msgid_plural "cart.item_count"
-msgstr[0] "%d item"
-msgstr[1] "%d items (dual)"
-msgstr[2] "%d items (few)"
-msgstr[3] "%d items (many)"
+#: src/dusk/ui/frame/settings/uisettings.c
+msgid "ui.settings.tabs.display"
+msgstr "Display"
 
-#: ui/notifications.c:71
-msgid ""
-"ui.multiline_help"
-msgstr ""
-"Line one of the help text.\n"
-"Line two continues here.\n"
-"Line three ends here."
+#: src/dusk/ui/frame/settings/uisettings.c
+msgid "ui.settings.tabs.audio"
+msgstr "Audio"
 
-#: ui/errors.c:90
-msgid ""
-"error.upload_failed.long"
-msgstr ""
-"Upload failed for file \"%s\".\n"
-"Please try again later or contact support."
+msgid "ui.settings.input.deadzone"
+msgstr "Deadzone"
 
-#: ui/messages.c:110
-msgid ""
-"user.invite_status"
-msgid_plural ""
-"user.invite_status"
-msgstr[0] ""
-"%s invited %d user.\n"
-"Please review the request."
-msgstr[1] ""
-"%s invited %d users (dual).\n"
-"Please review the requests."
-msgstr[2] ""
-"%s invited %d users (few).\n"
-"Please review the requests."
-msgstr[3] ""
-"%s invited %d users (many).\n"
-"Please review the requests."
+#: src/dusk/ui/frame/settings/uisettingsgeneral.c
+msgid "ui.settings.general.language"
+msgstr "Language"
+
+msgid "ui.settings.general.language_detail"
+msgstr "Takes effect after restarting the application."
+
+#: src/dusk/ui/frame/settings/uisettings.c
+msgid "ui.settings.apply"
+msgstr "Apply"
+
+#: src/dusk/ui/frame/uiconfirm.c
+msgid "ui.confirm.discard_changes"
+msgstr "Discard unsaved changes?"
+
+#: src/dusk/ui/frame/game/uigamemenu.c
+msgid "ui.game_menu.characters"
+msgstr "Characters"
+
+#: src/dusk/ui/frame/game/uigamemenu.c
+msgid "ui.game_menu.items"
+msgstr "Items"
+
+#: src/dusk/ui/frame/game/uigamemenu.c
+msgid "ui.game_menu.settings"
+msgstr "Settings"
+
+msgid "item.potion.name"
+msgstr "Potion"
+
+msgid "item.potato.name"
+msgstr "Potato"
+
+msgid "item.apple.name"
+msgstr "Apple"

assets/locale/es_MX.po

@@ -0,0 +1,70 @@
+msgid ""
+msgstr ""
+"Project-Id-Version: ExampleApp 1.0\n"
+"Language: es\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Plural-Forms: nplurals=2; plural=(n==1 ? 0 : 1);\n"
+
+#: ui/menu.c:10
+msgid "ui.title"
+msgstr ""
+"Bienvenido"
+
+#: src/dusk/ui/frame/settings/uisettings.c
+msgid "ui.settings.tabs.general"
+msgstr "General"
+
+#: src/dusk/ui/frame/settings/uisettings.c
+msgid "ui.settings.tabs.input"
+msgstr "Entrada"
+
+#: src/dusk/ui/frame/settings/uisettings.c
+msgid "ui.settings.tabs.display"
+msgstr "Pantalla"
+
+#: src/dusk/ui/frame/settings/uisettings.c
+msgid "ui.settings.tabs.audio"
+msgstr "Audio"
+
+msgid "ui.settings.input.deadzone"
+msgstr "Deadzone"
+
+#: src/dusk/ui/frame/settings/uisettingsgeneral.c
+msgid "ui.settings.general.language"
+msgstr "Idioma"
+
+#: src/dusk/ui/frame/settings/uisettingsgeneral.c
+msgid "ui.settings.general.language_detail"
+msgstr "Se aplica después de reiniciar la aplicación."
+
+#: src/dusk/ui/frame/settings/uisettings.c
+msgid "ui.settings.apply"
+msgstr "Aplicar"
+
+#: src/dusk/ui/frame/uiconfirm.c
+msgid "ui.confirm.discard_changes"
+msgstr "¿Descartar los cambios no guardados?"
+
+#: src/dusk/ui/frame/game/uigamemenu.c
+msgid "ui.game_menu.characters"
+msgstr "Personajes"
+
+#: src/dusk/ui/frame/game/uigamemenu.c
+msgid "ui.game_menu.items"
+msgstr "Objetos"
+
+#: src/dusk/ui/frame/game/uigamemenu.c
+msgid "ui.game_menu.settings"
+msgstr "Configuración"
+
+#: src/dusk/rpg/item/item.json
+msgid "item.potion.name"
+msgstr "Poción"
+
+#: src/dusk/rpg/item/item.json
+msgid "item.potato.name"
+msgstr "Papa"
+
+#: src/dusk/rpg/item/item.json
+msgid "item.apple.name"
+msgstr "Manzana"

assets/locale/jp_JP.po

@@ -0,0 +1,70 @@
+msgid ""
+msgstr ""
+"Project-Id-Version: ExampleApp 1.0\n"
+"Language: ja\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Plural-Forms: nplurals=1; plural=(0);\n"
+
+#: ui/menu.c:10
+msgid "ui.title"
+msgstr ""
+"歓迎"
+
+#: src/dusk/ui/frame/settings/uisettings.c
+msgid "ui.settings.tabs.general"
+msgstr "一般"
+
+#: src/dusk/ui/frame/settings/uisettings.c
+msgid "ui.settings.tabs.input"
+msgstr "入力"
+
+#: src/dusk/ui/frame/settings/uisettings.c
+msgid "ui.settings.tabs.display"
+msgstr "表示"
+
+#: src/dusk/ui/frame/settings/uisettings.c
+msgid "ui.settings.tabs.audio"
+msgstr "オーディオ"
+
+msgid "ui.settings.input.deadzone"
+msgstr "デッドゾーン"
+
+#: src/dusk/ui/frame/settings/uisettingsgeneral.c
+msgid "ui.settings.general.language"
+msgstr "言語"
+
+#: src/dusk/ui/frame/settings/uisettingsgeneral.c
+msgid "ui.settings.general.language_detail"
+msgstr "アプリケーションを再起動すると適用されます。"
+
+#: src/dusk/ui/frame/settings/uisettings.c
+msgid "ui.settings.apply"
+msgstr "適用"
+
+#: src/dusk/ui/frame/uiconfirm.c
+msgid "ui.confirm.discard_changes"
+msgstr "未保存の変更を破棄しますか？"
+
+#: src/dusk/ui/frame/game/uigamemenu.c
+msgid "ui.game_menu.characters"
+msgstr "キャラクター"
+
+#: src/dusk/ui/frame/game/uigamemenu.c
+msgid "ui.game_menu.items"
+msgstr "アイテム"
+
+#: src/dusk/ui/frame/game/uigamemenu.c
+msgid "ui.game_menu.settings"
+msgstr "設定"
+
+#: src/dusk/rpg/item/item.json
+msgid "item.potion.name"
+msgstr "ポーション"
+
+#: src/dusk/rpg/item/item.json
+msgid "item.potato.name"
+msgstr "ジャガイモ"
+
+#: src/dusk/rpg/item/item.json
+msgid "item.apple.name"
+msgstr "リンゴ"

assets/map/testmap/chunks/-1_0_0.json

@@ -0,0 +1 @@
+{"tiles": [[1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [0, 0], [0, 0], [0, 0], [0, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [0, 0], [0, 0], [0, 0], [0, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [0, 0], [0, 0], [0, 0], [0, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [0, 0], [0, 0], [0, 0], [0, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [0, 0], [0, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [0, 0], [0, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [0, 0], [0, 0], [0, 0], [0, 0], [0, 0], [0, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [0, 0], [0, 0], [0, 0], [0, 0], [0, 0], [0, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [0, 0], [0, 0], [0, 0], [0, 0], [0, 0], [0, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0]], "meshes": [{"model": "models/chunks/chunk_-1_0_0_0.json", "offset": [0.0, 0.0, 0.0]}, {"model": "models/buildings/house_4_4.json", "offset": [2.0, 1.0, 0.0]}, {"model": "models/buildings/house_6_3.json", "offset": [1.0, 9.0, 0.0]}, {"model": "models/buildings/house_2_2.json", "offset": [12.0, 6.0, 0.0]}]}

assets/map/testmap/chunks/0_1_0.json

@@ -0,0 +1 @@
+{"tiles": [[1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [0, 0], [0, 0], [0, 0], [0, 0], [0, 0], [0, 0], [0, 0], [0, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [0, 0], [0, 0], [0, 0], [0, 0], [0, 0], [0, 0], [0, 0], [0, 0], [1, 0], [1, 0], [0, 0], [0, 0], [0, 0], [1, 0], [1, 0], [1, 0], [0, 0], [0, 0], [0, 0], [0, 0], [0, 0], [0, 0], [0, 0], [0, 0], [1, 0], [1, 0], [0, 0], [0, 0], [0, 0], [1, 0], [1, 0], [1, 0], [0, 0], [0, 0], [0, 0], [0, 0], [0, 0], [0, 0], [0, 0], [0, 0], [1, 0], [1, 0], [0, 0], [0, 0], [0, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [0, 0], [0, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [0, 0], [0, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0]], "meshes": [{"model": "models/chunks/chunk_0_1_0_0.json", "offset": [0.0, 0.0, 0.0]}, {"model": "models/buildings/house_8_4.json", "offset": [1.0, 1.0, 0.0]}, {"model": "models/buildings/house_3_3.json", "offset": [11.0, 2.0, 0.0]}, {"model": "models/buildings/house_2_2.json", "offset": [3.0, 11.0, 0.0]}]}

assets/map/testmap/chunks/1_0_0.json

@@ -0,0 +1 @@
+{"tiles": [[1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [0, 0], [0, 0], [0, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [0, 0], [0, 0], [0, 0], [1, 0], [1, 0], [1, 0], [0, 0], [0, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [0, 0], [0, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [0, 0], [0, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [0, 0], [0, 0], [0, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [0, 0], [0, 0], [0, 0], [1, 0], [0, 0], [0, 0], [0, 0], [0, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [0, 0], [0, 0], [0, 0], [0, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [0, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0]], "meshes": [{"model": "models/chunks/chunk_1_0_0_0.json", "offset": [0.0, 0.0, 0.0]}, {"model": "models/buildings/house_3_2.json", "offset": [1.0, 1.0, 0.0]}, {"model": "models/buildings/house_2_3.json", "offset": [7.0, 2.0, 0.0]}, {"model": "models/buildings/house_4_2.json", "offset": [1.0, 8.0, 0.0]}, {"model": "models/buildings/house_1_1.json", "offset": [11.0, 10.0, 0.0]}, {"model": "models/buildings/house_5_2.json", "offset": [13.0, 6.0, 0.0]}]}

assets/map/testmap/chunks/1_1_0.json

@@ -0,0 +1 @@
+{"tiles": [[1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [0, 0], [0, 0], [0, 0], [0, 0], [0, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [0, 0], [0, 0], [0, 0], [0, 0], [0, 0], [1, 0], [1, 0], [0, 0], [0, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [0, 0], [0, 0], [0, 0], [0, 0], [0, 0], [1, 0], [1, 0], [0, 0], [0, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [0, 0], [0, 0], [0, 0], [0, 0], [0, 0], [1, 0], [1, 0], [0, 0], [0, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [0, 0], [0, 0], [0, 0], [0, 0], [0, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [0, 0], [0, 0], [0, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0]], "meshes": [{"model": "models/chunks/chunk_1_1_0_0.json", "offset": [0.0, 0.0, 0.0]}, {"model": "models/buildings/house_5_5.json", "offset": [3.0, 2.0, 0.0]}, {"model": "models/buildings/house_2_3.json", "offset": [10.0, 3.0, 0.0]}, {"model": "models/buildings/house_3_1.json", "offset": [1.0, 12.0, 0.0]}]}

assets/map/testmap/chunks/2_0_0.json

@@ -0,0 +1 @@
+{"tiles": [[1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 3], [1, 3], [1, 3], [1, 3], [1, 3], [1, 3], [1, 0], [1, 0], [1, 0], [1, 0], [0, 0], [0, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 3], [1, 3], [1, 3], [1, 3], [1, 3], [1, 3], [1, 0], [1, 0], [1, 0], [1, 0], [0, 0], [0, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 3], [1, 3], [1, 3], [1, 3], [1, 3], [1, 3], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [4, 2], [4, 2], [4, 2], [4, 2], [4, 2], [4, 2], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [4, 1], [4, 1], [4, 1], [4, 1], [4, 1], [4, 1], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [4, 0], [4, 0], [4, 0], [4, 0], [4, 0], [4, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0], [1, 0]], "meshes": [{"model": "models/chunks/chunk_2_0_0_0.json", "offset": [0.0, 0.0, 0.0]}]}

assets/map/testmap/map.json

@@ -0,0 +1,13 @@
+{
+  "name": "Test Map",
+  "entities": [
+    { "type": "player", "position": [10, 2, 0], "direction": "north" },
+    { "type": "item", "position": [12, 2, 0], "item": "POTION", "quantity": 1 },
+    {
+      "type": "npc",
+      "position": [8, 8, 1],
+      "path": [[4, 4, 0], [10, 10, 1], [4, 4, 0], [10, 10, 1]],
+      "cutscene": "test_npc"
+    }
+  ]
+}

cmake/targets/dolphin.cmake

@@ -16,6 +16,9 @@ target_compile_definitions(${DUSK_LIBRARY_TARGET_NAME} PUBLIC
   DOL=1
   ISO=2
   DUSK_DOLPHIN_BUILD_TYPE=${DUSK_DOLPHIN_BUILD_TYPE}
+  # GameCube/Wii PowerPC is always big-endian; declare it at compile time
+  # like every other target instead of relying on endian.h's runtime probe.
+  DUSK_PLATFORM_ENDIAN_BIG
 )
 
 # Custom compiler flags

cmake/targets/linux.cmake

@@ -36,7 +36,7 @@ target_compile_definitions(${DUSK_LIBRARY_TARGET_NAME} PUBLIC
   # DUSK_OPENGL_LEGACY
   DUSK_LINUX
   DUSK_DISPLAY_SIZE_DYNAMIC
-  DUSK_DISPLAY_WIDTH_DEFAULT=640
+  DUSK_DISPLAY_WIDTH_DEFAULT=854
   DUSK_DISPLAY_HEIGHT_DEFAULT=480
   DUSK_DISPLAY_SCREEN_HEIGHT=240
   DUSK_INPUT_KEYBOARD

cmake/targets/psp.cmake

@@ -56,6 +56,7 @@ target_compile_definitions(${DUSK_BINARY_TARGET_NAME} PUBLIC
   DUSK_DISPLAY_HEIGHT=272
   DUSK_THREAD_PTHREAD
   DUSK_TIME_DYNAMIC
+  DUSK_DISPLAY_OVERSCAN=6
 )
 
 if(NOT CMAKE_BUILD_TYPE STREQUAL "Debug")

src/dusk/asset/asset.c

@@ -59,20 +59,28 @@ assetentry_t * assetGetEntry(
     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;
-    }
+  // We did not find one existing. Find first available slot, reaping
+  // zero-ref entries to make room if none are immediately available.
+  bool_t reaped = false;
+  for(;;) {
+    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);
+      if(entry->state == ASSET_ENTRY_STATE_NOT_STARTED) {
+        assetEntryInit(entry, name, type, input);
+        return entry;
+      }
+      entry++;
+    } while(entry < ASSET.entries + ASSET_ENTRY_COUNT_MAX);
+
+    if(reaped) break;
+    reaped = true;
+    errorCatch(assetReapUnused());
+  }
 
   assertUnreachable("No available asset entry slots.");
   return NULL;
@@ -191,6 +199,32 @@ void assetUnlockEntry(assetentry_t *entry) {
   assetEntryUnlock(entry);
 }
 
+errorret_t assetReapUnused(void) {
+  assertIsMainThread("assetReapUnused must be called from the main thread.");
+
+  // Repeatedly find and dispose zero-ref LOADED entries until none remain.
+  // This handles dependency chains where an entry (e.g. a model) holds refs
+  // on child entries (mesh, texture): dispose parents first so child ref
+  // counts drop to zero, then pick up the children on the next pass. Without
+  // this, a forward-only scan fails when a shared child entry appears before
+  // a parent that still holds a ref to it.
+  bool_t any;
+  do {
+    any = false;
+    assetentry_t *entry = ASSET.entries;
+    do {
+      if(entry->type == ASSET_LOADER_TYPE_NULL) { entry++; continue; }
+      if(entry->state != ASSET_ENTRY_STATE_LOADED) { entry++; continue; }
+      if(entry->refs.count > 0) { entry++; continue; }
+      errorChain(assetEntryDispose(entry));
+      any = true;
+      entry++;
+    } while(entry < ASSET.entries + ASSET_ENTRY_COUNT_MAX);
+  } while(any);
+
+  errorOk();
+}
+
 errorret_t assetUpdate(void) {
   assertIsMainThread("assetUpdate must be called from the main thread.");
 
@@ -324,30 +358,6 @@ errorret_t assetUpdate(void) {
     }
   } while(loading < ASSET.loading + ASSET_LOADING_COUNT_MAX);
 
-
-  // Reap unused entries.
-  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();
 }
 
@@ -413,26 +423,7 @@ errorret_t assetDispose(void) {
   assertIsMainThread("Must be called from the main thread.");
   threadStop(&ASSET.loadThread);
 
-  // Drain-dispose: repeatedly find and dispose zero-ref LOADED entries
-  // until none remain. This handles dependency chains where an entry
-  // (e.g. a model) holds refs on child entries (mesh, texture): dispose
-  // parents first so child ref counts drop to zero, then pick up the
-  // children on the next pass. Without this, a forward-only scan fails
-  // when a shared child entry appears before a parent that still holds a
-  // ref to it.
-  bool_t any;
-  do {
-    any = false;
-    assetentry_t *e = ASSET.entries;
-    do {
-      if(e->type == ASSET_LOADER_TYPE_NULL) { e++; continue; }
-      if(e->state != ASSET_ENTRY_STATE_LOADED) { e++; continue; }
-      if(e->refs.count > 0) { e++; continue; }
-      errorChain(assetEntryDispose(e));
-      any = true;
-      e++;
-    } while(e < ASSET.entries + ASSET_ENTRY_COUNT_MAX);
-  } while(any);
+  errorChain(assetReapUnused());
 
   // Cleanup zip file.
   if(ASSET.zip != NULL) {

src/dusk/asset/asset.h

@@ -23,8 +23,8 @@
 #define ASSET_FILE_NAME "dusk.dsk"
 #define ASSET_HEADER_SIZE 3
 
-#define ASSET_LOADING_COUNT_MAX 20
-#define ASSET_ENTRY_COUNT_MAX 128
+#define ASSET_LOADING_COUNT_MAX 10
+#define ASSET_ENTRY_COUNT_MAX 64
 
 typedef struct asset_s {
   zip_t *zip;
@@ -112,6 +112,16 @@ void assetUnlock(const char_t *name);
  */
 void assetUnlockEntry(assetentry_t *entry);
 
+/**
+ * Frees every currently unreferenced (zero-ref) loaded asset entry. Repeats
+ * until a full pass frees nothing further, since disposing a parent entry
+ * (e.g. a model) may drop a child entry's (e.g. a mesh) ref count to zero,
+ * making it eligible for reaping too.
+ *
+ * @return An error code if any entry could not be disposed properly.
+ */
+errorret_t assetReapUnused(void);
+
 /**
  * Requires an asset entry to be loaded. This will block until the asset entry
  * is fully loaded.

src/dusk/asset/loader/chunk/assetchunkloader.c

@@ -8,40 +8,17 @@
 #include "assetchunkloader.h"
 #include "assert/assert.h"
 #include "util/memory.h"
-#include "util/endian.h"
+#include "util/string.h"
 #include "asset/loader/assetloading.h"
 #include "asset/loader/assetentry.h"
 #include "asset/loader/assetloader.h"
+#include "asset/loader/json/assetjsonloader.h"
 #include "asset/asset.h"
+#include "yyjson.h"
 
 errorret_t assetChunkLoaderAsync(assetloading_t *loading) {
   assertNotNull(loading, "Loading cannot be NULL");
   assertNotMainThread("Should be called from an async thread.");
-
-  if(loading->loading.chunk.state != ASSET_CHUNK_LOADING_STATE_READ_FILE) {
-    errorOk();
-  }
-
-  assertNull(loading->loading.chunk.data, "Data already defined?");
-
-  assetfile_t *file = &loading->loading.chunk.file;
-  assetLoaderErrorChain(loading,
-    assetFileInit(file, loading->entry->name, NULL, NULL)
-  );
-
-  uint8_t *data = memoryAllocate(file->size);
-  assetLoaderErrorChain(loading, assetFileOpen(file));
-  assetLoaderErrorChain(loading, assetFileRead(file, data, file->size));
-  assetLoaderErrorChain(loading, assetFileClose(file));
-  assetLoaderErrorChain(loading, assetFileDispose(file));
-  assertTrue(
-    file->lastRead == file->size,
-    "Failed to read entire chunk file."
-  );
-
-  loading->loading.chunk.data = data;
-  loading->loading.chunk.state = ASSET_CHUNK_LOADING_STATE_PARSE;
-  loading->entry->state = ASSET_ENTRY_STATE_PENDING_SYNC;
   errorOk();
 }
 
@@ -54,12 +31,141 @@ errorret_t assetChunkLoaderSync(assetloading_t *loading) {
 
   switch(loading->loading.chunk.state) {
     case ASSET_CHUNK_LOADING_STATE_INITIAL:
-      loading->loading.chunk.state = ASSET_CHUNK_LOADING_STATE_READ_FILE;
-      loading->entry->state = ASSET_ENTRY_STATE_PENDING_ASYNC;
+      loading->loading.chunk.state = ASSET_CHUNK_LOADING_STATE_LOAD_JSON;
+      loading->entry->state = ASSET_ENTRY_STATE_PENDING_SYNC;
       errorOk();
 
-    case ASSET_CHUNK_LOADING_STATE_PARSE:
-      break;
+    case ASSET_CHUNK_LOADING_STATE_LOAD_JSON: {
+      // Lock the chunk's JSON as a sub-asset. The entry key is prefixed
+      // with "json:" to avoid a type-collision with the chunk entry
+      // itself (both share the same filename). The JSON loader reads
+      // the real file path supplied in the input.
+      char_t jsonKey[ASSET_FILE_NAME_MAX];
+      stringFormat(
+        jsonKey, sizeof(jsonKey), "json:%s", loading->entry->name
+      );
+      assetloaderinput_t jsonInput;
+      memoryZero(&jsonInput, sizeof(jsonInput));
+      stringCopy(
+        jsonInput.json.path, loading->entry->name, ASSET_FILE_NAME_MAX
+      );
+      assetentry_t *jsonEntry = assetLock(
+        jsonKey, ASSET_LOADER_TYPE_JSON, &jsonInput
+      );
+      errorret_t ret = assetRequireLoaded(jsonEntry);
+      if(errorIsNotOk(ret)) {
+        assetUnlockEntry(jsonEntry);
+        loading->entry->state = ASSET_ENTRY_STATE_ERROR;
+        errorChain(ret);
+      }
+
+      yyjson_val *root = yyjson_doc_get_root(jsonEntry->data.json);
+
+      yyjson_val *tilesVal = yyjson_obj_get(root, "tiles");
+      if(
+        !tilesVal || !yyjson_is_arr(tilesVal) ||
+        yyjson_arr_size(tilesVal) != CHUNK_TILE_COUNT
+      ) {
+        assetUnlockEntry(jsonEntry);
+        loading->entry->state = ASSET_ENTRY_STATE_ERROR;
+        errorThrow(
+          "Chunk JSON 'tiles' must have exactly %d entries",
+          CHUNK_TILE_COUNT
+        );
+      }
+
+      out->tiles = memoryAllocate(CHUNK_TILE_COUNT * sizeof(tile_t));
+      size_t tileIdx, tileMax;
+      yyjson_val *tileVal;
+      yyjson_arr_foreach(tilesVal, tileIdx, tileMax, tileVal) {
+        yyjson_val *shapeVal = yyjson_arr_get(tileVal, 0);
+        yyjson_val *zVal = yyjson_arr_get(tileVal, 1);
+        if(
+          !yyjson_is_arr(tileVal) || yyjson_arr_size(tileVal) != 2 ||
+          !yyjson_is_int(shapeVal) || !yyjson_is_int(zVal)
+        ) {
+          memoryFree(out->tiles);
+          out->tiles = NULL;
+          assetUnlockEntry(jsonEntry);
+          loading->entry->state = ASSET_ENTRY_STATE_ERROR;
+          errorThrow("Chunk JSON tile entries must be [shape, z] arrays");
+        }
+        out->tiles[tileIdx] = (tile_t){
+          .shape = (tileshape_t)yyjson_get_int(shapeVal),
+          .z = (uint8_t)yyjson_get_int(zVal)
+        };
+      }
+
+      yyjson_val *meshesVal = yyjson_obj_get(root, "meshes");
+      out->meshCount = 0;
+      if(meshesVal && yyjson_is_arr(meshesVal)) {
+        size_t meshCount = yyjson_arr_size(meshesVal);
+        if(meshCount > CHUNK_MESH_COUNT_MAX) {
+          memoryFree(out->tiles);
+          out->tiles = NULL;
+          assetUnlockEntry(jsonEntry);
+          loading->entry->state = ASSET_ENTRY_STATE_ERROR;
+          errorThrow(
+            "Chunk JSON 'meshes' exceeds CHUNK_MESH_COUNT_MAX (%d)",
+            CHUNK_MESH_COUNT_MAX
+          );
+        }
+
+        size_t meshIdx, meshMax;
+        yyjson_val *meshVal;
+        yyjson_arr_foreach(meshesVal, meshIdx, meshMax, meshVal) {
+          yyjson_val *modelVal = yyjson_obj_get(meshVal, "model");
+          if(!modelVal || !yyjson_is_str(modelVal)) {
+            memoryFree(out->tiles);
+            out->tiles = NULL;
+            assetUnlockEntry(jsonEntry);
+            loading->entry->state = ASSET_ENTRY_STATE_ERROR;
+            errorThrow("Chunk JSON mesh entry missing 'model' string");
+          }
+          const char_t *modelStr = yyjson_get_str(modelVal);
+          size_t modelLen = yyjson_get_len(modelVal);
+          if(modelLen >= CHUNK_MESH_NAME_MAX) {
+            memoryFree(out->tiles);
+            out->tiles = NULL;
+            assetUnlockEntry(jsonEntry);
+            loading->entry->state = ASSET_ENTRY_STATE_ERROR;
+            errorThrow(
+              "Chunk JSON model path '%s' exceeds max length", modelStr
+            );
+          }
+          memoryCopy(out->modelNames[meshIdx], modelStr, modelLen + 1);
+
+          vec3 offset = { 0.0f, 0.0f, 0.0f };
+          yyjson_val *offsetVal = yyjson_obj_get(meshVal, "offset");
+          if(
+            offsetVal && yyjson_is_arr(offsetVal) &&
+            yyjson_arr_size(offsetVal) == 3
+          ) {
+            size_t offIdx, offMax;
+            yyjson_val *offElem;
+            yyjson_arr_foreach(offsetVal, offIdx, offMax, offElem) {
+              if(yyjson_is_num(offElem)) {
+                offset[offIdx] = (float_t)yyjson_get_num(offElem);
+              }
+            }
+          }
+          glm_vec3_copy(offset, out->meshOffsets[meshIdx]);
+        }
+        out->meshCount = (uint8_t)meshCount;
+      }
+
+      assetUnlockEntry(jsonEntry);
+
+      if(out->meshCount == 0) {
+        loading->entry->state = ASSET_ENTRY_STATE_LOADED;
+        errorOk();
+      }
+
+      loading->loading.chunk.state = ASSET_CHUNK_LOADING_STATE_LOAD_MODELS;
+      loading->loading.chunk.modelIndex = 0;
+      loading->entry->state = ASSET_ENTRY_STATE_PENDING_SYNC;
+      errorOk();
+    }
 
     case ASSET_CHUNK_LOADING_STATE_LOAD_MODELS:
       while(loading->loading.chunk.modelIndex < out->meshCount) {
@@ -91,64 +197,6 @@ errorret_t assetChunkLoaderSync(assetloading_t *loading) {
     default:
       errorOk();
   }
-
-  uint8_t *data = loading->loading.chunk.data;
-  assertNotNull(data, "Chunk data should have been loaded by now.");
-
-  if(data[0] != 'D' || data[1] != 'C' || data[2] != 'F') {
-    memoryFree(data);
-    assetLoaderErrorThrow(loading, "Invalid chunk file header");
-  }
-
-  uint32_t version = endianLittleToHost32(*(uint32_t *)(data + 4));
-  if(version != ASSET_CHUNK_FILE_VERSION) {
-    memoryFree(data);
-    assetLoaderErrorThrow(
-      loading, "Unsupported chunk file version %u", version
-    );
-  }
-
-  size_t offset = 8;
-
-  size_t tileSize = CHUNK_TILE_COUNT * sizeof(tile_t);
-  memoryCopy(out->tiles, data + offset, tileSize);
-  offset += tileSize;
-
-  out->meshCount = data[offset];
-  offset += sizeof(uint8_t);
-  assertTrue(
-    out->meshCount <= CHUNK_MESH_COUNT_MAX,
-    "Chunk mesh count exceeds maximum."
-  );
-
-  for(uint8_t m = 0; m < out->meshCount; m++) {
-    uint8_t nameLen = 0;
-    while(
-      data[offset + nameLen] != '\0' &&
-      nameLen < CHUNK_MESH_NAME_MAX - 1
-    ) {
-      nameLen++;
-    }
-    memoryCopy(out->modelNames[m], data + offset, nameLen);
-    out->modelNames[m][nameLen] = '\0';
-    offset += nameLen + 1;
-
-    memoryCopy(out->meshOffsets[m], data + offset, sizeof(vec3));
-    offset += sizeof(vec3);
-  }
-
-  memoryFree(data);
-  loading->loading.chunk.data = NULL;
-
-  if(out->meshCount == 0) {
-    loading->entry->state = ASSET_ENTRY_STATE_LOADED;
-    errorOk();
-  }
-
-  loading->loading.chunk.state = ASSET_CHUNK_LOADING_STATE_LOAD_MODELS;
-  loading->loading.chunk.modelIndex = 0;
-  loading->entry->state = ASSET_ENTRY_STATE_PENDING_SYNC;
-  errorOk();
 }
 
 errorret_t assetChunkDispose(assetentry_t *entry) {
@@ -157,6 +205,12 @@ errorret_t assetChunkDispose(assetentry_t *entry) {
   assertIsMainThread("Must be called from the main thread.");
 
   assetchunkoutput_t *out = &entry->data.chunk;
+
+  if(out->tiles != NULL) {
+    memoryFree(out->tiles);
+    out->tiles = NULL;
+  }
+
   for(uint8_t m = 0; m < out->meshCount; m++) {
     if(out->modelEntries[m] == NULL) continue;
     assetUnlockEntry(out->modelEntries[m]);

src/dusk/asset/loader/chunk/assetchunkloader.h

@@ -9,8 +9,6 @@
 #include "asset/assetfile.h"
 #include "rpg/overworld/chunk.h"
 
-#define ASSET_CHUNK_FILE_VERSION 3
-
 typedef struct assetloading_s assetloading_t;
 typedef struct assetentry_s assetentry_t;
 
@@ -20,21 +18,17 @@ typedef struct {
 
 typedef enum {
   ASSET_CHUNK_LOADING_STATE_INITIAL,
-  ASSET_CHUNK_LOADING_STATE_READ_FILE,
-  ASSET_CHUNK_LOADING_STATE_PARSE,
-  ASSET_CHUNK_LOADING_STATE_LOAD_MODELS,
-  ASSET_CHUNK_LOADING_STATE_DONE
+  ASSET_CHUNK_LOADING_STATE_LOAD_JSON,
+  ASSET_CHUNK_LOADING_STATE_LOAD_MODELS
 } assetchunkloadingstate_t;
 
 typedef struct {
-  assetfile_t file;
   assetchunkloadingstate_t state;
-  uint8_t *data;
   uint8_t modelIndex;
 } assetchunkloaderloading_t;
 
 typedef struct {
-  tile_t tiles[CHUNK_TILE_COUNT];
+  tile_t *tiles;
   uint8_t meshCount;
   char_t modelNames[CHUNK_MESH_COUNT_MAX][CHUNK_MESH_NAME_MAX];
   vec3 meshOffsets[CHUNK_MESH_COUNT_MAX];
@@ -42,9 +36,9 @@ typedef struct {
 } assetchunkoutput_t;
 
 /**
- * Asynchronous loader for chunk assets. Reads the raw DCF file bytes into
- * the loading buffer so the sync phase can parse without blocking the
- * main thread on I/O.
+ * Asynchronous loader for chunk assets. No-op - the chunk's JSON file is
+ * loaded via a JSON sub-asset in the sync phase (see assetChunkLoaderSync),
+ * which handles its own async file I/O.
  *
  * @param loading Loading information for the asset being loaded.
  * @return Error code indicating success or failure of the load operation.
@@ -52,9 +46,22 @@ typedef struct {
 errorret_t assetChunkLoaderAsync(assetloading_t *loading);
 
 /**
- * Synchronous loader for chunk assets. Validates the DCF binary previously
- * read by the async phase and populates the output assetchunkoutput_t with
- * tile data and model paths.
+ * Synchronous loader for chunk assets. Locks and parses the chunk's JSON
+ * file (tiles plus referenced model paths/offsets), then locks each
+ * referenced model asset before marking the entry loaded.
+ *
+ * Expected JSON shape:
+ *   {
+ *     "tiles": [ [shape, z], ... ]  // exactly CHUNK_TILE_COUNT entries,
+ *                                   // one per (x, y) column, x-major
+ *     "meshes": [
+ *       { "model": "models/chunks/chunk_0_0_0_0.json",
+ *         "offset": [0.0, 0.0, 0.0] }
+ *     ]
+ *   }
+ * "meshes" is optional; each entry's "offset" defaults to [0, 0, 0] if
+ * omitted. By convention mesh index 0 is the chunk's terrain and the
+ * rest are props (see sceneOverworldDrawChunksBase/Props).
  *
  * @param loading Loading information for the asset being loaded.
  * @return Error code indicating success or failure of the load operation.

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

@@ -48,8 +48,20 @@ errorret_t assetMeshLoaderAsync(assetloading_t *loading) {
   uint32_t vertCount = endianLittleToHost32(*(uint32_t *)(raw + 8));
   meshvertex_t *vertices = NULL;
   if(vertCount > 0) {
-    vertices = memoryAllocate(vertCount * sizeof(meshvertex_t));
+    // 32-byte (cache-line) aligned: GX_SetArray + DCFlushRange on Dolphin
+    // require this for the DMA'd vertex data to actually reach the GPU
+    // coherently. Static compiled-in vertex arrays happen to get this from
+    // the linker; a plain memoryAllocate here would not.
+    vertices = memoryAlign(32, vertCount * sizeof(meshvertex_t));
     memoryCopy(vertices, raw + 12, vertCount * sizeof(meshvertex_t));
+
+    for(uint32_t v = 0; v < vertCount; v++) {
+      vertices[v].uv[0] = endianLittleToHostFloat(vertices[v].uv[0]);
+      vertices[v].uv[1] = endianLittleToHostFloat(vertices[v].uv[1]);
+      vertices[v].pos[0] = endianLittleToHostFloat(vertices[v].pos[0]);
+      vertices[v].pos[1] = endianLittleToHostFloat(vertices[v].pos[1]);
+      vertices[v].pos[2] = endianLittleToHostFloat(vertices[v].pos[2]);
+    }
   }
   memoryFree(raw);
 
@@ -103,18 +115,22 @@ errorret_t assetMeshLoaderSync(assetloading_t *loading) {
     out->vertices = NULL;
     errorChain(ret);
   }
+  out->meshInitialized = true;
 
   ret = meshFlush(&out->mesh, 0, (int32_t)vertCount);
   if(errorIsNotOk(ret)) {
     loading->entry->state = ASSET_ENTRY_STATE_ERROR;
     meshDispose(&out->mesh);
+    out->meshInitialized = false;
     memoryFree(out->vertices);
     out->vertices = NULL;
     errorChain(ret);
   }
 
-  #ifndef DUSK_OPENGL_LEGACY
-    // VBO owns the data now; CPU copy is no longer needed.
+  #if defined(DUSK_OPENGL) && !defined(DUSK_OPENGL_LEGACY)
+    // VBO owns the data now; CPU copy is no longer needed. The platform
+    // mesh object itself still needs meshDispose later - tracked via
+    // out->meshInitialized, independent of the CPU buffer's lifetime.
     memoryFree(out->vertices);
     out->vertices = NULL;
   #endif
@@ -129,8 +145,11 @@ errorret_t assetMeshDispose(assetentry_t *entry) {
   assertIsMainThread("Must be called from the main thread.");
 
   assetmeshoutput_t *out = &entry->data.mesh;
-  if(out->vertices != NULL) {
+  if(out->meshInitialized) {
     errorChain(meshDispose(&out->mesh));
+    out->meshInitialized = false;
+  }
+  if(out->vertices != NULL) {
     memoryFree(out->vertices);
     out->vertices = NULL;
   }

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

@@ -30,6 +30,7 @@ typedef struct {
 
 typedef struct {
   mesh_t mesh;
+  bool_t meshInitialized;
   meshvertex_t *vertices;
 } assetmeshoutput_t;
 

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

@@ -513,9 +513,10 @@ errorret_t assetLocaleGetString(
   // Skip blanks, comments, etc and start looking for msgid's
   errorChain(assetLocaleLineSkipBlanks(&reader, lineBuffer));
 
-  while(!reader.eof) {
+  while(true) {
     // Is this msgid?
     if(memoryCompare(lineBuffer, "msgid", 5) != 0) {
+      if(reader.eof) break;
       errorChain(assetFileLineReaderNext(&reader));
       msgidBuffer[0] = '\0';
       continue;
@@ -539,7 +540,7 @@ errorret_t assetLocaleGetString(
   }
   
   // We are either going to see a msgstr or a msgid_plural
-  while(!reader.eof) {
+  while(true) {
     errorChain(assetLocaleLineSkipBlanks(&reader, lineBuffer));
 
     // Is msgid_plural?

src/dusk/console/console.c

@@ -17,7 +17,7 @@ console_t CONSOLE;
 
 void consoleInit(void) {
   memoryZero(&CONSOLE, sizeof(console_t));
-  CONSOLE.visible = true;
+  CONSOLE.visible = false;
 
   #ifdef DUSK_CONSOLE_POSIX
     threadMutexInit(&CONSOLE.printMutex);

src/dusk/engine/engine.c

@@ -10,6 +10,7 @@
 #include "time/time.h"
 #include "input/input.h"
 #include "locale/localemanager.h"
+#include "rpg/item/item.h"
 #include "rpg/rpg.h"
 #include "display/display.h"
 #include "scene/scene.h"
@@ -39,6 +40,7 @@ errorret_t engineInit(const int32_t argc, const char_t **argv) {
   errorChain(assetInit());
   // errorChain(saveInit());
   errorChain(localeManagerInit());
+  errorChain(itemInit());
   errorChain(displayInit());
   errorChain(uiInit());
   errorChain(rpgInit());

src/dusk/input/input.c

@@ -17,6 +17,7 @@ input_t INPUT;
 
 errorret_t inputInit(void) {
   memoryZero(&INPUT, sizeof(input_t));
+  INPUT.deadzone = INPUT_DEADZONE_DEFAULT;
 
   for(uint8_t i = 0; i < INPUT_ACTION_COUNT; i++) {
     INPUT.actions[i].action = (inputaction_t)i;

src/dusk/input/input.h

@@ -12,11 +12,15 @@
 
 #define INPUT_LISTENER_PRESSED_MAX 16
 #define INPUT_LISTENER_RELEASED_MAX INPUT_LISTENER_PRESSED_MAX
+#define INPUT_DEADZONE_DEFAULT 0.1f
 
 typedef struct {
   inputactiondata_t actions[INPUT_ACTION_COUNT];
 
   inputplatform_t platform;
+
+  /** User-configured gamepad axis deadzone (0.0f to 1.0f). */
+  float_t deadzone;
 } input_t;
 
 extern input_t INPUT;

src/dusk/locale/localeinfo.h

@@ -16,4 +16,14 @@ typedef struct {
 static const localeinfo_t LOCALE_EN_US = {
   .name = "en-US",
   .file = "locale/en_US.po",
+};
+
+static const localeinfo_t LOCALE_JP_JP = {
+  .name = "ja-JP",
+  .file = "locale/jp_JP.po",
+};
+
+static const localeinfo_t LOCALE_ES_MX = {
+  .name = "es-MX",
+  .file = "locale/es_MX.po",
 };

src/dusk/rpg/CMakeLists.txt

@@ -11,6 +11,7 @@ target_sources(${DUSK_LIBRARY_TARGET_NAME}
 )
 
 # Subdirs
+add_subdirectory(battle)
 add_subdirectory(cutscene)
 add_subdirectory(entity)
 add_subdirectory(overworld)

src/dusk/rpg/battle/CMakeLists.txt

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

src/dusk/rpg/battle/battle.c

@@ -0,0 +1,223 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#include "battle.h"
+#include "assert/assert.h"
+#include "util/memory.h"
+
+battle_t BATTLE;
+
+void battleInit(void) {
+  memoryZero(&BATTLE, sizeof(battle_t));
+  for(uint8_t i = 0; i < BATTLE_FIGHTER_COUNT_MAX; i++) {
+    BATTLE.fighters[i].id = i;
+  }
+}
+
+uint8_t battleGetAvailableFighter(void) {
+  for(uint8_t i = 0; i < BATTLE_FIGHTER_COUNT_MAX; i++) {
+    if(BATTLE.fighters[i].status == BATTLE_FIGHTER_STATUS_NULL) return i;
+  }
+
+  return 0xFF;
+}
+
+battlefighter_t *battleAddFighter(
+  const battlefighterteam_t team,
+  const battlefightercontroller_t controller,
+  const battlefighterstats_t stats,
+  const uint16_t healthMax,
+  const uint16_t mpMax
+) {
+  const uint8_t index = battleGetAvailableFighter();
+  if(index == 0xFF) return NULL;
+
+  battlefighter_t *fighter = &BATTLE.fighters[index];
+  battleFighterInit(fighter, team, controller, stats, healthMax, mpMax);
+  return fighter;
+}
+
+void battleStart(
+  const battleencountertype_t encounterType,
+  const bool_t fleeAvailable
+) {
+  assertTrue(encounterType < BATTLE_ENCOUNTER_COUNT, "Invalid encounter type");
+
+  BATTLE.encounterType = encounterType;
+  BATTLE.fleeAvailable = fleeAvailable;
+  BATTLE.result = BATTLE_RESULT_NONE;
+  BATTLE.round = 1;
+  BATTLE.turnIndex = 0;
+  battleBuildTurnOrder(true);
+
+  BATTLE.active = true;
+}
+
+void battleDispose(void) {
+  battleInit();
+}
+
+battlefighter_t *battleGetCurrentFighter(void) {
+  if(!BATTLE.active) return NULL;
+  if(BATTLE.turnIndex >= BATTLE.turnCount) return NULL;
+  return &BATTLE.fighters[BATTLE.turnOrder[BATTLE.turnIndex]];
+}
+
+uint8_t battleGetAliveCount(const battlefighterteam_t team) {
+  uint8_t count = 0;
+  for(uint8_t i = 0; i < BATTLE_FIGHTER_COUNT_MAX; i++) {
+    if(BATTLE.fighters[i].team != team) continue;
+    if(!battleFighterIsAlive(&BATTLE.fighters[i])) continue;
+    count++;
+  }
+  return count;
+}
+
+void battleResolveAttack(
+  battlefighter_t *attacker,
+  battlefighter_t *defender
+) {
+  assertNotNull(attacker, "Attacker cannot be NULL");
+  assertNotNull(defender, "Defender cannot be NULL");
+
+  const int32_t rawDamage =
+    (int32_t)attacker->stats.attack - (int32_t)defender->stats.defense;
+  const uint16_t damage = rawDamage > 0 ? (uint16_t)rawDamage : 1;
+
+  defender->health = damage >= defender->health ? 0 : defender->health - damage;
+  if(defender->health == 0) defender->status = BATTLE_FIGHTER_STATUS_DEAD;
+}
+
+void battleNextTurn(void) {
+  BATTLE.turnIndex++;
+  if(BATTLE.turnIndex < BATTLE.turnCount) return;
+
+  BATTLE.round++;
+  BATTLE.turnIndex = 0;
+  battleBuildTurnOrder(false);
+}
+
+battleresult_t battleCheckResult(void) {
+  if(BATTLE.result != BATTLE_RESULT_NONE) return BATTLE.result;
+
+  if(battleGetAliveCount(BATTLE_FIGHTER_TEAM_ALLY) == 0) {
+    BATTLE.result = BATTLE_RESULT_LOSS;
+  } else if(battleGetAliveCount(BATTLE_FIGHTER_TEAM_ENEMY) == 0) {
+    BATTLE.result = BATTLE_RESULT_WIN;
+  }
+
+  return BATTLE.result;
+}
+
+void battlePlayerAttack(const uint8_t targetIndex) {
+  battlefighter_t *attacker = battleGetCurrentFighter();
+  if(attacker == NULL) return;
+  if(attacker->controller != BATTLE_FIGHTER_CONTROLLER_PLAYER) return;
+  if(targetIndex >= BATTLE_FIGHTER_COUNT_MAX) return;
+
+  battlefighter_t *defender = &BATTLE.fighters[targetIndex];
+  if(!battleFighterIsAlive(defender)) return;
+
+  battleResolveAttack(attacker, defender);
+  battleCheckResult();
+  if(BATTLE.result == BATTLE_RESULT_NONE) battleNextTurn();
+}
+
+void battlePlayerFlee(void) {
+  battlefighter_t *fighter = battleGetCurrentFighter();
+  if(fighter == NULL) return;
+  if(fighter->controller != BATTLE_FIGHTER_CONTROLLER_PLAYER) return;
+  if(!BATTLE.fleeAvailable) return;
+
+  BATTLE.result = BATTLE_RESULT_FLED;
+}
+
+void battleUpdate(void) {
+  if(!BATTLE.active) return;
+  if(BATTLE.result != BATTLE_RESULT_NONE) return;
+
+  battlefighter_t *current = battleGetCurrentFighter();
+  if(current == NULL) return;
+
+  if(!battleFighterIsAlive(current)) {
+    battleNextTurn();
+    return;
+  }
+
+  if(current->controller != BATTLE_FIGHTER_CONTROLLER_AI) return;
+
+  battlefighter_t *target = battleAIChooseTarget(current);
+  if(target != NULL) battleResolveAttack(current, target);
+
+  battleCheckResult();
+  if(BATTLE.result == BATTLE_RESULT_NONE) battleNextTurn();
+}
+
+void battleBuildTurnOrder(const bool_t applyEncounterBias) {
+  BATTLE.turnCount = 0;
+  for(uint8_t i = 0; i < BATTLE_FIGHTER_COUNT_MAX; i++) {
+    if(!battleFighterIsAlive(&BATTLE.fighters[i])) continue;
+    BATTLE.turnOrder[BATTLE.turnCount++] = i;
+  }
+
+  // Insertion sort by speed descending -- fine for BATTLE_FIGHTER_COUNT_MAX.
+  for(uint8_t i = 1; i < BATTLE.turnCount; i++) {
+    const uint8_t key = BATTLE.turnOrder[i];
+    const uint16_t keySpeed = BATTLE.fighters[key].stats.speed;
+
+    int8_t j = (int8_t)i - 1;
+    while(
+      j >= 0 && BATTLE.fighters[BATTLE.turnOrder[j]].stats.speed < keySpeed
+    ) {
+      BATTLE.turnOrder[j + 1] = BATTLE.turnOrder[j];
+      j--;
+    }
+    BATTLE.turnOrder[j + 1] = key;
+  }
+
+  if(!applyEncounterBias) return;
+
+  if(BATTLE.encounterType == BATTLE_ENCOUNTER_PLAYER_ADVANTAGE) {
+    battleMoveTeamFirst(BATTLE_FIGHTER_TEAM_ALLY);
+  } else if(BATTLE.encounterType == BATTLE_ENCOUNTER_BACK_ATTACK) {
+    battleMoveTeamFirst(BATTLE_FIGHTER_TEAM_ENEMY);
+  }
+}
+
+void battleMoveTeamFirst(const battlefighterteam_t team) {
+  uint8_t sorted[BATTLE_FIGHTER_COUNT_MAX];
+  uint8_t count = 0;
+
+  for(uint8_t i = 0; i < BATTLE.turnCount; i++) {
+    if(BATTLE.fighters[BATTLE.turnOrder[i]].team != team) continue;
+    sorted[count++] = BATTLE.turnOrder[i];
+  }
+  for(uint8_t i = 0; i < BATTLE.turnCount; i++) {
+    if(BATTLE.fighters[BATTLE.turnOrder[i]].team == team) continue;
+    sorted[count++] = BATTLE.turnOrder[i];
+  }
+
+  memoryCopy(BATTLE.turnOrder, sorted, sizeof(uint8_t) * BATTLE.turnCount);
+}
+
+battlefighter_t *battleAIChooseTarget(const battlefighter_t *fighter) {
+  const battlefighterteam_t enemyTeam =
+    fighter->team == BATTLE_FIGHTER_TEAM_ALLY ?
+      BATTLE_FIGHTER_TEAM_ENEMY : BATTLE_FIGHTER_TEAM_ALLY;
+
+  battlefighter_t *weakest = NULL;
+  for(uint8_t i = 0; i < BATTLE_FIGHTER_COUNT_MAX; i++) {
+    battlefighter_t *candidate = &BATTLE.fighters[i];
+    if(candidate->team != enemyTeam) continue;
+    if(!battleFighterIsAlive(candidate)) continue;
+    if(weakest == NULL || candidate->health < weakest->health) {
+      weakest = candidate;
+    }
+  }
+
+  return weakest;
+}

src/dusk/rpg/battle/battle.h

@@ -0,0 +1,194 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#pragma once
+#include "battlefighter.h"
+
+#define BATTLE_FIGHTER_COUNT_MAX 8
+
+typedef enum {
+  BATTLE_ENCOUNTER_REGULAR,
+  BATTLE_ENCOUNTER_PLAYER_ADVANTAGE,
+  BATTLE_ENCOUNTER_BACK_ATTACK,
+
+  BATTLE_ENCOUNTER_COUNT
+} battleencountertype_t;
+
+typedef enum {
+  BATTLE_RESULT_NONE,
+  BATTLE_RESULT_WIN,
+  BATTLE_RESULT_LOSS,
+  BATTLE_RESULT_FLED,
+
+  BATTLE_RESULT_COUNT
+} battleresult_t;
+
+typedef struct {
+  bool_t active;
+  battlefighter_t fighters[BATTLE_FIGHTER_COUNT_MAX];
+
+  battleencountertype_t encounterType;
+  bool_t fleeAvailable;
+  battleresult_t result;
+
+  // Fighter indices (into fighters[]), sorted for the current round.
+  uint8_t turnOrder[BATTLE_FIGHTER_COUNT_MAX];
+  uint8_t turnCount;
+  uint8_t turnIndex;
+  uint16_t round;
+} battle_t;
+
+extern battle_t BATTLE;
+
+/**
+ * Initializes the battle system. Marks it as inactive with no fighters.
+ */
+void battleInit(void);
+
+/**
+ * Gets an available (unused) fighter slot index.
+ *
+ * @return The index of an available fighter slot, or 0xFF if none are
+ *         available.
+ */
+uint8_t battleGetAvailableFighter(void);
+
+/**
+ * Adds a fighter to the battle in the next available slot.
+ *
+ * @param team The team the fighter belongs to.
+ * @param controller Who makes decisions for the fighter.
+ * @param stats The fighter's base combat stats.
+ * @param healthMax The fighter's maximum health.
+ * @param mpMax The fighter's maximum mp.
+ * @return Pointer to the newly added fighter, or NULL if the battle is
+ *         already full.
+ */
+battlefighter_t *battleAddFighter(
+  const battlefighterteam_t team,
+  const battlefightercontroller_t controller,
+  const battlefighterstats_t stats,
+  const uint16_t healthMax,
+  const uint16_t mpMax
+);
+
+/**
+ * Starts the battle: builds the opening turn order (biased by
+ * encounterType for the first round only) and marks the battle active.
+ * Call once every fighter has been added via battleAddFighter.
+ *
+ * @param encounterType Determines the opening round's turn order.
+ * @param fleeAvailable Whether the party may attempt to flee this battle.
+ */
+void battleStart(
+  const battleencountertype_t encounterType,
+  const bool_t fleeAvailable
+);
+
+/**
+ * Disposes of the battle, clearing all fighters and marking it inactive.
+ */
+void battleDispose(void);
+
+/**
+ * Returns the fighter whose turn it currently is.
+ *
+ * @return Pointer to the active fighter, or NULL if the battle isn't
+ *         active or has no living fighters left to act.
+ */
+battlefighter_t *battleGetCurrentFighter(void);
+
+/**
+ * Returns the number of living fighters on a team.
+ *
+ * @param team The team to count.
+ * @return Count of living fighters on that team.
+ */
+uint8_t battleGetAliveCount(const battlefighterteam_t team);
+
+/**
+ * Resolves a physical attack from attacker onto defender: damage is the
+ * attacker's attack stat minus the defender's defense stat (minimum 1),
+ * subtracted from the defender's health. The defender is marked dead
+ * once health reaches 0.
+ *
+ * @param attacker The attacking fighter.
+ * @param defender The defending fighter.
+ */
+void battleResolveAttack(
+  battlefighter_t *attacker,
+  battlefighter_t *defender
+);
+
+/**
+ * Ends the current fighter's turn and advances to the next fighter in
+ * the turn order, starting a new round (rebuilding turn order purely by
+ * speed) once every fighter in the current round has acted.
+ */
+void battleNextTurn(void);
+
+/**
+ * Checks whether the battle has been won or lost, updating and
+ * returning BATTLE.result. Does nothing if a result has already been
+ * set (e.g. by a successful flee).
+ *
+ * @return The battle's current result.
+ */
+battleresult_t battleCheckResult(void);
+
+/**
+ * Submits the current fighter's attack against a target, if it is
+ * currently a player-controlled fighter's turn. Resolves the attack,
+ * checks for a battle result, and advances the turn.
+ *
+ * @param targetIndex Index into BATTLE.fighters of the target.
+ */
+void battlePlayerAttack(const uint8_t targetIndex);
+
+/**
+ * Submits a flee attempt for the current fighter's turn, if it is
+ * currently a player-controlled fighter's turn and fleeing is
+ * available for this battle. Always succeeds, ending the battle with
+ * BATTLE_RESULT_FLED.
+ */
+void battlePlayerFlee(void);
+
+/**
+ * Updates the battle simulation for one frame: resolves the current
+ * fighter's turn automatically if AI-controlled, otherwise waits for a
+ * player action via battlePlayerAttack/battlePlayerFlee. No-op if the
+ * battle isn't active or already has a result.
+ */
+void battleUpdate(void);
+
+/**
+ * Rebuilds BATTLE.turnOrder/turnCount from every currently living
+ * fighter, sorted by speed descending.
+ *
+ * @param applyEncounterBias If true, reorders the freshly speed-sorted
+ * queue so BATTLE.encounterType's favoured team goes first (used only
+ * for the opening round).
+ */
+void battleBuildTurnOrder(const bool_t applyEncounterBias);
+
+/**
+ * Stably partitions BATTLE.turnOrder so every fighter on the given team
+ * comes first, preserving each side's relative (speed-sorted) order.
+ *
+ * @param team The team to move to the front of the turn order.
+ */
+void battleMoveTeamFirst(const battlefighterteam_t team);
+
+/**
+ * Picks an AI target for fighter: the lowest-health living fighter on
+ * the opposing team.
+ *
+ * @param fighter The AI-controlled fighter choosing a target.
+ * @return The chosen target, or NULL if the opposing team has no
+ *         living fighters.
+ */
+battlefighter_t *battleAIChooseTarget(const battlefighter_t *fighter);

src/dusk/rpg/battle/battlefighter.c

@@ -0,0 +1,43 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#include "battlefighter.h"
+#include "assert/assert.h"
+#include "util/memory.h"
+
+void battleFighterInit(
+  battlefighter_t *fighter,
+  const battlefighterteam_t team,
+  const battlefightercontroller_t controller,
+  const battlefighterstats_t stats,
+  const uint16_t healthMax,
+  const uint16_t mpMax
+) {
+  assertNotNull(fighter, "Fighter pointer cannot be NULL");
+  assertTrue(team < BATTLE_FIGHTER_TEAM_COUNT, "Invalid fighter team");
+  assertTrue(
+    controller < BATTLE_FIGHTER_CONTROLLER_COUNT,
+    "Invalid fighter controller"
+  );
+
+  const uint8_t id = fighter->id;
+  memoryZero(fighter, sizeof(battlefighter_t));
+  fighter->id = id;
+  fighter->status = BATTLE_FIGHTER_STATUS_NORMAL;
+  fighter->team = team;
+  fighter->controller = controller;
+  fighter->stats = stats;
+  fighter->healthMax = healthMax;
+  fighter->health = healthMax;
+  fighter->mpMax = mpMax;
+  fighter->mp = mpMax;
+}
+
+bool_t battleFighterIsAlive(const battlefighter_t *fighter) {
+  assertNotNull(fighter, "Fighter pointer cannot be NULL");
+  return fighter->status == BATTLE_FIGHTER_STATUS_NORMAL;
+}

src/dusk/rpg/battle/battlefighter.h

@@ -0,0 +1,87 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#pragma once
+#include "error/error.h"
+
+// An empty status means the slot in BATTLE.fighters is unused.
+typedef enum {
+  BATTLE_FIGHTER_STATUS_NULL,
+
+  BATTLE_FIGHTER_STATUS_NORMAL,
+  BATTLE_FIGHTER_STATUS_DEAD,
+
+  BATTLE_FIGHTER_STATUS_COUNT
+} battlefighterstatus_t;
+
+typedef enum {
+  BATTLE_FIGHTER_TEAM_ALLY,
+  BATTLE_FIGHTER_TEAM_ENEMY,
+
+  BATTLE_FIGHTER_TEAM_COUNT
+} battlefighterteam_t;
+
+typedef enum {
+  BATTLE_FIGHTER_CONTROLLER_PLAYER,
+  BATTLE_FIGHTER_CONTROLLER_AI,
+
+  BATTLE_FIGHTER_CONTROLLER_COUNT
+} battlefightercontroller_t;
+
+// Base combat stats, kept separate from the resource pools (health/mp) on
+// battlefighter_t so that equipment/buffs can later modify them without
+// touching current health/mp state.
+typedef struct {
+  uint16_t attack;
+  uint16_t defense;
+  uint16_t magic;
+  uint16_t speed;
+  uint16_t luck;
+} battlefighterstats_t;
+
+typedef struct {
+  uint8_t id;
+  battlefighterstatus_t status;
+  battlefighterteam_t team;
+  battlefightercontroller_t controller;
+
+  uint16_t health;
+  uint16_t healthMax;
+  uint16_t mp;
+  uint16_t mpMax;
+
+  battlefighterstats_t stats;
+} battlefighter_t;
+
+/**
+ * Initializes a battle fighter in place, filling health/mp to their maximum
+ * values and setting its status to normal.
+ *
+ * @param fighter Pointer to the fighter to initialize.
+ * @param team The team the fighter belongs to.
+ * @param controller Who makes decisions for the fighter.
+ * @param stats The fighter's base combat stats.
+ * @param healthMax The fighter's maximum health.
+ * @param mpMax The fighter's maximum mp.
+ */
+void battleFighterInit(
+  battlefighter_t *fighter,
+  const battlefighterteam_t team,
+  const battlefightercontroller_t controller,
+  const battlefighterstats_t stats,
+  const uint16_t healthMax,
+  const uint16_t mpMax
+);
+
+/**
+ * Returns true if the fighter is in a state where it can still act (i.e.
+ * is not dead).
+ *
+ * @param fighter Pointer to the fighter to check.
+ * @returns True if the fighter can act.
+ */
+bool_t battleFighterIsAlive(const battlefighter_t *fighter);

src/dusk/rpg/battle/party.c

@@ -0,0 +1,71 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#include "party.h"
+#include "assert/assert.h"
+#include "util/memory.h"
+
+party_t PARTY;
+
+void partyInit(void) {
+  memoryZero(&PARTY, sizeof(party_t));
+  for(uint8_t i = 0; i < PARTY_MEMBER_COUNT_MAX; i++) {
+    PARTY.members[i].id = i;
+  }
+  for(uint8_t i = 0; i < PARTY_ACTIVE_SIZE_MAX; i++) {
+    PARTY.order[i] = PARTY_ORDER_EMPTY;
+  }
+}
+
+uint8_t partyGetAvailableMember(void) {
+  for(uint8_t i = 0; i < PARTY_MEMBER_COUNT_MAX; i++) {
+    if(PARTY.members[i].status == BATTLE_FIGHTER_STATUS_NULL) return i;
+  }
+
+  return 0xFF;
+}
+
+battlefighter_t *partyAddMember(
+  const battlefighterstats_t stats,
+  const uint16_t healthMax,
+  const uint16_t mpMax
+) {
+  const uint8_t index = partyGetAvailableMember();
+  if(index == 0xFF) return NULL;
+
+  battlefighter_t *member = &PARTY.members[index];
+  battleFighterInit(
+    member, BATTLE_FIGHTER_TEAM_ALLY, BATTLE_FIGHTER_CONTROLLER_PLAYER,
+    stats, healthMax, mpMax
+  );
+
+  for(uint8_t i = 0; i < PARTY_ACTIVE_SIZE_MAX; i++) {
+    if(PARTY.order[i] != PARTY_ORDER_EMPTY) continue;
+    PARTY.order[i] = index;
+    break;
+  }
+
+  return member;
+}
+
+battlefighter_t *partyGetOrderMember(const uint8_t slot) {
+  assertTrue(slot < PARTY_ACTIVE_SIZE_MAX, "Invalid party order slot");
+
+  const uint8_t index = PARTY.order[slot];
+  if(index == PARTY_ORDER_EMPTY) return NULL;
+  return &PARTY.members[index];
+}
+
+void partySetOrder(const uint8_t slot, const uint8_t memberIndex) {
+  assertTrue(slot < PARTY_ACTIVE_SIZE_MAX, "Invalid party order slot");
+  assertTrue(
+    memberIndex == PARTY_ORDER_EMPTY || memberIndex < PARTY_MEMBER_COUNT_MAX,
+    "Invalid party member index"
+  );
+
+  PARTY.order[slot] = memberIndex;
+}

src/dusk/rpg/battle/party.h

@@ -0,0 +1,73 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#pragma once
+#include "battlefighter.h"
+
+#define PARTY_MEMBER_COUNT_MAX 4
+#define PARTY_ACTIVE_SIZE_MAX 3
+#define PARTY_ORDER_EMPTY 0xFF
+
+typedef struct {
+  battlefighter_t members[PARTY_MEMBER_COUNT_MAX];
+
+  // Maps an active battle slot to the roster member filling it, or
+  // PARTY_ORDER_EMPTY if the slot is unfilled. Only the first
+  // PARTY_ACTIVE_SIZE_MAX of the PARTY_MEMBER_COUNT_MAX roster members
+  // can be in the active lineup at once.
+  uint8_t order[PARTY_ACTIVE_SIZE_MAX];
+} party_t;
+
+extern party_t PARTY;
+
+/**
+ * Initializes the party system with an empty roster and order.
+ */
+void partyInit(void);
+
+/**
+ * Gets an available (unused) party member slot index.
+ *
+ * @return The index of an available slot, or 0xFF if the party is full.
+ */
+uint8_t partyGetAvailableMember(void);
+
+/**
+ * Adds a member to the party roster in the next available slot. Party
+ * members are always allies controlled by the player. If there is a
+ * free active order slot, the new member is placed into it.
+ *
+ * @param stats The member's base combat stats.
+ * @param healthMax The member's maximum health.
+ * @param mpMax The member's maximum mp.
+ * @return Pointer to the newly added party member, or NULL if the party is
+ *         already full.
+ */
+battlefighter_t *partyAddMember(
+  const battlefighterstats_t stats,
+  const uint16_t healthMax,
+  const uint16_t mpMax
+);
+
+/**
+ * Gets the roster member currently occupying an active order slot.
+ *
+ * @param slot The active order slot to query.
+ * @return Pointer to the member in that slot, or NULL if the slot is
+ *         empty.
+ */
+battlefighter_t *partyGetOrderMember(const uint8_t slot);
+
+/**
+ * Assigns a roster member to an active order slot, replacing whatever
+ * was there. Use PARTY_ORDER_EMPTY to clear a slot.
+ *
+ * @param slot The active order slot to assign.
+ * @param memberIndex The roster member index to place there, or
+ *        PARTY_ORDER_EMPTY to clear the slot.
+ */
+void partySetOrder(const uint8_t slot, const uint8_t memberIndex);

src/dusk/rpg/cutscene/CMakeLists.txt

@@ -6,6 +6,7 @@
 # Sources
 target_sources(${DUSK_LIBRARY_TARGET_NAME}
   PUBLIC
+    cutscene.c
     cutscenesystem.c
 )
 

src/dusk/rpg/cutscene/cutscene.c

@@ -0,0 +1,444 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#include "cutscene.h"
+#include "assert/assert.h"
+#include "util/memory.h"
+#include "util/string.h"
+#include "asset/asset.h"
+#include "asset/loader/assetloader.h"
+#include "asset/loader/assetentry.h"
+#include "asset/loader/json/assetjsonloader.h"
+#include "rpg/cutscene/cutscenesystem.h"
+#include "rpg/entity/entitytype.h"
+#include "rpg/entity/entitydir.h"
+#include "ui/rpg/uiemoji.h"
+#include "yyjson.h"
+
+static cutscenejsoncacheentry_t CUTSCENE_JSON_CACHE[CUTSCENE_JSON_CACHE_MAX];
+static uint32_t CUTSCENE_JSON_CACHE_COUNT;
+
+errorret_t cutsceneJsonParsePause(yyjson_val *val, cutscenepause_t *outPause) {
+  assertNotNull(outPause, "Output pause pointer cannot be NULL");
+  if(!val || !yyjson_is_str(val)) {
+    errorThrow("Cutscene pause value must be a string");
+  }
+
+  const char_t *str = yyjson_get_str(val);
+  if(stringEquals(str, "NONE")) {
+    *outPause = CUTSCENE_PAUSE_NONE;
+  } else if(stringEquals(str, "DEFAULT")) {
+    *outPause = CUTSCENE_PAUSE_DEFAULT;
+  } else if(stringEquals(str, "ALL")) {
+    *outPause = CUTSCENE_PAUSE_ALL;
+  } else {
+    errorThrow("Unknown cutscene pause value '%s'", str);
+  }
+
+  errorOk();
+}
+
+errorret_t cutsceneJsonParseEntityIndex(yyjson_val *val, uint8_t *outIndex) {
+  assertNotNull(outIndex, "Output entity index pointer cannot be NULL");
+
+  if(val && yyjson_is_str(val)) {
+    const char_t *str = yyjson_get_str(val);
+    if(stringEquals(str, "interact")) {
+      *outIndex = CUTSCENE_ENTITY_INTERACT;
+    } else if(stringEquals(str, "interacted")) {
+      *outIndex = CUTSCENE_ENTITY_INTERACTED;
+    } else if(stringEquals(str, "lastCreated")) {
+      *outIndex = CUTSCENE_ENTITY_LAST_CREATED;
+    } else {
+      errorThrow("Unknown entity index sentinel '%s'", str);
+    }
+    errorOk();
+  }
+
+  if(!val || !yyjson_is_int(val)) {
+    errorThrow("Entity index must be a number or sentinel string");
+  }
+  *outIndex = (uint8_t)yyjson_get_int(val);
+  errorOk();
+}
+
+errorret_t cutsceneJsonParseWorldPos(yyjson_val *val, worldpos_t *outPos) {
+  assertNotNull(outPos, "Output position pointer cannot be NULL");
+  if(!val || !yyjson_is_arr(val) || yyjson_arr_size(val) != 3) {
+    errorThrow("Position must be a [x, y, z] array");
+  }
+
+  worldunit_t comps[3];
+  size_t idx, max;
+  yyjson_val *elem;
+  yyjson_arr_foreach(val, idx, max, elem) {
+    if(!yyjson_is_num(elem)) {
+      errorThrow("Position elements must be numbers");
+    }
+    comps[idx] = (worldunit_t)yyjson_get_num(elem);
+  }
+
+  *outPos = (worldpos_t){ comps[0], comps[1], comps[2] };
+  errorOk();
+}
+
+errorret_t cutsceneItemCreateFromJson(
+  yyjson_val *obj,
+  cutsceneitem_t *outItem,
+  worldpos_t *waypoints,
+  const uint8_t waypointsMax
+) {
+  assertNotNull(obj, "Cutscene item JSON object cannot be NULL");
+  assertNotNull(outItem, "Output item pointer cannot be NULL");
+
+  yyjson_val *typeVal = yyjson_obj_get(obj, "type");
+  if(!typeVal || !yyjson_is_str(typeVal)) {
+    errorThrow("Cutscene item JSON missing 'type' string");
+  }
+  const char_t *typeStr = yyjson_get_str(typeVal);
+
+  memoryZero(outItem, sizeof(cutsceneitem_t));
+
+  if(stringEquals(typeStr, "text")) {
+    yyjson_val *textVal = yyjson_obj_get(obj, "text");
+    if(!textVal || !yyjson_is_str(textVal)) {
+      errorThrow("Cutscene 'text' item missing 'text' string");
+    }
+
+    outItem->type = CUTSCENE_ITEM_TYPE_TEXT;
+    stringCopy(
+      outItem->text.text, yyjson_get_str(textVal), CUTSCENE_TEXT_MAX_CHARS
+    );
+  } else if(stringEquals(typeStr, "textMini")) {
+    yyjson_val *textVal = yyjson_obj_get(obj, "text");
+    if(!textVal || !yyjson_is_str(textVal)) {
+      errorThrow("Cutscene 'textMini' item missing 'text' string");
+    }
+
+    worldpos_t pos;
+    errorChain(
+      cutsceneJsonParseWorldPos(yyjson_obj_get(obj, "position"), &pos)
+    );
+
+    yyjson_val *durVal = yyjson_obj_get(obj, "duration");
+    if(!durVal || !yyjson_is_num(durVal)) {
+      errorThrow("Cutscene 'textMini' item missing 'duration' number");
+    }
+
+    outItem->type = CUTSCENE_ITEM_TYPE_TEXT_MINI;
+    stringCopy(
+      outItem->textMini.text, yyjson_get_str(textVal),
+      CUTSCENE_TEXT_MINI_MAX_CHARS
+    );
+    outItem->textMini.position[0] = (float_t)pos.x;
+    outItem->textMini.position[1] = (float_t)pos.y;
+    outItem->textMini.position[2] = (float_t)pos.z;
+    outItem->textMini.duration = (float_t)yyjson_get_num(durVal);
+  } else if(stringEquals(typeStr, "textMiniHide")) {
+    yyjson_val *indexVal = yyjson_obj_get(obj, "index");
+    if(!indexVal || !yyjson_is_int(indexVal)) {
+      errorThrow("Cutscene 'textMiniHide' item missing 'index' number");
+    }
+
+    outItem->type = CUTSCENE_ITEM_TYPE_TEXT_MINI_HIDE;
+    outItem->textMiniHide.index = (uint8_t)yyjson_get_int(indexVal);
+  } else if(stringEquals(typeStr, "wait")) {
+    yyjson_val *durVal = yyjson_obj_get(obj, "duration");
+    if(!durVal || !yyjson_is_num(durVal)) {
+      errorThrow("Cutscene 'wait' item missing 'duration' number");
+    }
+
+    outItem->type = CUTSCENE_ITEM_TYPE_WAIT;
+    outItem->wait = (float_t)yyjson_get_num(durVal);
+  } else if(stringEquals(typeStr, "entityAdd")) {
+    yyjson_val *entityTypeVal = yyjson_obj_get(obj, "entityType");
+    if(!entityTypeVal || !yyjson_is_str(entityTypeVal)) {
+      errorThrow("Cutscene 'entityAdd' item missing 'entityType' string");
+    }
+    const char_t *entityTypeStr = yyjson_get_str(entityTypeVal);
+
+    entitytype_t entityType;
+    if(stringEquals(entityTypeStr, "player")) {
+      entityType = ENTITY_TYPE_PLAYER;
+    } else if(stringEquals(entityTypeStr, "npc")) {
+      entityType = ENTITY_TYPE_NPC;
+    } else if(stringEquals(entityTypeStr, "item")) {
+      entityType = ENTITY_TYPE_ITEM;
+    } else {
+      errorThrow(
+        "Cutscene 'entityAdd' has unknown entityType '%s'", entityTypeStr
+      );
+    }
+
+    worldpos_t pos;
+    errorChain(
+      cutsceneJsonParseWorldPos(yyjson_obj_get(obj, "position"), &pos)
+    );
+
+    outItem->type = CUTSCENE_ITEM_TYPE_ENTITY_ADD;
+    outItem->entityAdd.entityType = entityType;
+    outItem->entityAdd.position = pos;
+  } else if(stringEquals(typeStr, "entityRemove")) {
+    uint8_t entityIndex;
+    errorChain(cutsceneJsonParseEntityIndex(
+      yyjson_obj_get(obj, "entityIndex"), &entityIndex
+    ));
+
+    outItem->type = CUTSCENE_ITEM_TYPE_ENTITY_REMOVE;
+    outItem->entityRemove.entityIndex = entityIndex;
+  } else if(stringEquals(typeStr, "entityTurn")) {
+    uint8_t entityIndex;
+    errorChain(cutsceneJsonParseEntityIndex(
+      yyjson_obj_get(obj, "entityIndex"), &entityIndex
+    ));
+
+    yyjson_val *dirVal = yyjson_obj_get(obj, "direction");
+    if(!dirVal || !yyjson_is_str(dirVal)) {
+      errorThrow("Cutscene 'entityTurn' item missing 'direction' string");
+    }
+    const char_t *dirStr = yyjson_get_str(dirVal);
+
+    entitydir_t direction;
+    if(stringEquals(dirStr, "north")) {
+      direction = ENTITY_DIR_NORTH;
+    } else if(stringEquals(dirStr, "east")) {
+      direction = ENTITY_DIR_EAST;
+    } else if(stringEquals(dirStr, "south")) {
+      direction = ENTITY_DIR_SOUTH;
+    } else if(stringEquals(dirStr, "west")) {
+      direction = ENTITY_DIR_WEST;
+    } else {
+      errorThrow("Cutscene 'entityTurn' has unknown direction '%s'", dirStr);
+    }
+
+    outItem->type = CUTSCENE_ITEM_TYPE_ENTITY_TURN;
+    outItem->entityTurn.entityIndex = entityIndex;
+    outItem->entityTurn.direction = direction;
+  } else if(stringEquals(typeStr, "entityWalkTo")) {
+    uint8_t entityIndex;
+    errorChain(cutsceneJsonParseEntityIndex(
+      yyjson_obj_get(obj, "entityIndex"), &entityIndex
+    ));
+
+    yyjson_val *positionsVal = yyjson_obj_get(obj, "positions");
+    if(!positionsVal || !yyjson_is_arr(positionsVal)) {
+      errorThrow("Cutscene 'entityWalkTo' item missing 'positions' array");
+    }
+    size_t count = yyjson_arr_size(positionsVal);
+    if(count == 0 || count > waypointsMax) {
+      errorThrow(
+        "Cutscene 'entityWalkTo' 'positions' must have 1-%d entries",
+        waypointsMax
+      );
+    }
+    assertNotNull(waypoints, "Waypoint storage cannot be NULL");
+
+    size_t idx, max;
+    yyjson_val *posVal;
+    yyjson_arr_foreach(positionsVal, idx, max, posVal) {
+      errorChain(cutsceneJsonParseWorldPos(posVal, &waypoints[idx]));
+    }
+
+    bool_t walkAround = true;
+    yyjson_val *walkAroundVal = yyjson_obj_get(obj, "walkAround");
+    if(walkAroundVal && yyjson_is_bool(walkAroundVal)) {
+      walkAround = yyjson_get_bool(walkAroundVal);
+    }
+
+    outItem->type = CUTSCENE_ITEM_TYPE_ENTITY_WALK_TO;
+    outItem->entityWalkTo.entityIndex = entityIndex;
+    outItem->entityWalkTo.positions = waypoints;
+    outItem->entityWalkTo.count = (uint8_t)count;
+    outItem->entityWalkTo.walkAround = walkAround;
+  } else if(stringEquals(typeStr, "entityWalkToEntity")) {
+    uint8_t entityIndex, targetEntityIndex;
+    errorChain(cutsceneJsonParseEntityIndex(
+      yyjson_obj_get(obj, "entityIndex"), &entityIndex
+    ));
+    errorChain(cutsceneJsonParseEntityIndex(
+      yyjson_obj_get(obj, "targetEntityIndex"), &targetEntityIndex
+    ));
+
+    yyjson_val *offsetXVal = yyjson_obj_get(obj, "offsetX");
+    yyjson_val *offsetYVal = yyjson_obj_get(obj, "offsetY");
+    if(
+      !offsetXVal || !yyjson_is_num(offsetXVal) ||
+      !offsetYVal || !yyjson_is_num(offsetYVal)
+    ) {
+      errorThrow(
+        "Cutscene 'entityWalkToEntity' item missing "
+        "'offsetX'/'offsetY' numbers"
+      );
+    }
+
+    outItem->type = CUTSCENE_ITEM_TYPE_ENTITY_WALK_TO_ENTITY;
+    outItem->entityWalkToEntity.entityIndex = entityIndex;
+    outItem->entityWalkToEntity.targetEntityIndex = targetEntityIndex;
+    outItem->entityWalkToEntity.offsetX =
+      (worldunit_t)yyjson_get_num(offsetXVal);
+    outItem->entityWalkToEntity.offsetY =
+      (worldunit_t)yyjson_get_num(offsetYVal);
+  } else if(stringEquals(typeStr, "entityTeleport")) {
+    uint8_t entityIndex;
+    errorChain(cutsceneJsonParseEntityIndex(
+      yyjson_obj_get(obj, "entityIndex"), &entityIndex
+    ));
+
+    worldpos_t pos;
+    errorChain(
+      cutsceneJsonParseWorldPos(yyjson_obj_get(obj, "position"), &pos)
+    );
+
+    outItem->type = CUTSCENE_ITEM_TYPE_ENTITY_TELEPORT;
+    outItem->entityTeleport.entityIndex = entityIndex;
+    outItem->entityTeleport.target = pos;
+  } else if(stringEquals(typeStr, "emoji")) {
+    uint8_t entityIndex;
+    errorChain(cutsceneJsonParseEntityIndex(
+      yyjson_obj_get(obj, "entityIndex"), &entityIndex
+    ));
+
+    yyjson_val *emojiTypeVal = yyjson_obj_get(obj, "emojiType");
+    if(!emojiTypeVal || !yyjson_is_str(emojiTypeVal)) {
+      errorThrow("Cutscene 'emoji' item missing 'emojiType' string");
+    }
+    const char_t *emojiTypeStr = yyjson_get_str(emojiTypeVal);
+
+    uiemojitype_t emojiType;
+    if(stringEquals(emojiTypeStr, "question")) {
+      emojiType = UI_EMOJI_QUESTION_MARK;
+    } else if(stringEquals(emojiTypeStr, "exclamation")) {
+      emojiType = UI_EMOJI_EXCLAMATION_MARK;
+    } else {
+      errorThrow(
+        "Cutscene 'emoji' has unknown emojiType '%s'", emojiTypeStr
+      );
+    }
+
+    yyjson_val *durVal = yyjson_obj_get(obj, "duration");
+    if(!durVal || !yyjson_is_num(durVal)) {
+      errorThrow("Cutscene 'emoji' item missing 'duration' number");
+    }
+
+    outItem->type = CUTSCENE_ITEM_TYPE_EMOJI;
+    outItem->emoji.entityIndex = entityIndex;
+    outItem->emoji.emojiType = emojiType;
+    outItem->emoji.duration = (float_t)yyjson_get_num(durVal);
+  } else if(stringEquals(typeStr, "shake")) {
+    yyjson_val *amountVal = yyjson_obj_get(obj, "amount");
+    yyjson_val *durVal = yyjson_obj_get(obj, "duration");
+    if(
+      !amountVal || !yyjson_is_int(amountVal) ||
+      !durVal || !yyjson_is_num(durVal)
+    ) {
+      errorThrow("Cutscene 'shake' item missing 'amount'/'duration' numbers");
+    }
+
+    outItem->type = CUTSCENE_ITEM_TYPE_SHAKE;
+    outItem->shake.amount = (uint8_t)yyjson_get_int(amountVal);
+    outItem->shake.duration = (float_t)yyjson_get_num(durVal);
+  } else if(stringEquals(typeStr, "setPause")) {
+    cutscenepause_t pause;
+    errorChain(
+      cutsceneJsonParsePause(yyjson_obj_get(obj, "pause"), &pause)
+    );
+
+    outItem->type = CUTSCENE_ITEM_TYPE_SET_PAUSE;
+    outItem->setPause = pause;
+  } else {
+    errorThrow("Cutscene item JSON has unknown 'type': %s", typeStr);
+  }
+
+  errorOk();
+}
+
+errorret_t cutsceneGetByName(
+  const char_t *name, const cutscene_t **outCutscene
+) {
+  assertNotNull(name, "Cutscene name cannot be NULL");
+  assertNotNull(outCutscene, "Output cutscene pointer cannot be NULL");
+  assertStrLenMax(name, CUTSCENE_JSON_NAME_MAX, "Cutscene name too long");
+
+  for(uint32_t i = 0; i < CUTSCENE_JSON_CACHE_COUNT; i++) {
+    if(!stringEquals(CUTSCENE_JSON_CACHE[i].name, name)) continue;
+    *outCutscene = &CUTSCENE_JSON_CACHE[i].cutscene;
+    errorOk();
+  }
+
+  if(CUTSCENE_JSON_CACHE_COUNT >= CUTSCENE_JSON_CACHE_MAX) {
+    errorThrow(
+      "Too many cutscenes loaded: exceeds CUTSCENE_JSON_CACHE_MAX (%d)",
+      CUTSCENE_JSON_CACHE_MAX
+    );
+  }
+
+  char_t path[CUTSCENE_JSON_NAME_MAX + 24];
+  stringFormat(path, sizeof(path), "cutscene/%s.json", name);
+
+  assetentry_t *entry = assetLock(path, ASSET_LOADER_TYPE_JSON, NULL);
+  errorret_t ret = assetRequireLoaded(entry);
+  if(errorIsNotOk(ret)) {
+    assetUnlockEntry(entry);
+    errorChain(ret);
+  }
+
+  yyjson_val *root = yyjson_doc_get_root(entry->data.json);
+
+  cutscenepause_t pause = CUTSCENE_PAUSE_DEFAULT;
+  yyjson_val *pauseVal = yyjson_obj_get(root, "pause");
+  if(pauseVal) {
+    errorret_t pauseRet = cutsceneJsonParsePause(pauseVal, &pause);
+    if(errorIsNotOk(pauseRet)) {
+      assetUnlockEntry(entry);
+      errorChain(pauseRet);
+    }
+  }
+
+  yyjson_val *itemsVal = yyjson_obj_get(root, "items");
+  if(!itemsVal || !yyjson_is_arr(itemsVal)) {
+    assetUnlockEntry(entry);
+    errorThrow("Cutscene '%s' JSON missing 'items' array", name);
+  }
+
+  size_t itemCount = yyjson_arr_size(itemsVal);
+  if(itemCount == 0 || itemCount > CUTSCENE_JSON_ITEM_COUNT_MAX) {
+    assetUnlockEntry(entry);
+    errorThrow(
+      "Cutscene '%s' 'items' must have 1-%d entries",
+      name, CUTSCENE_JSON_ITEM_COUNT_MAX
+    );
+  }
+
+  cutscenejsoncacheentry_t *cache =
+    &CUTSCENE_JSON_CACHE[CUTSCENE_JSON_CACHE_COUNT];
+  memoryZero(cache, sizeof(cutscenejsoncacheentry_t));
+  stringCopy(cache->name, name, CUTSCENE_JSON_NAME_MAX);
+
+  size_t idx, max;
+  yyjson_val *itemVal;
+  yyjson_arr_foreach(itemsVal, idx, max, itemVal) {
+    errorret_t itemRet = cutsceneItemCreateFromJson(
+      itemVal, &cache->items[idx], cache->waypoints[idx],
+      CUTSCENE_JSON_WAYPOINT_COUNT_MAX
+    );
+    if(errorIsNotOk(itemRet)) {
+      assetUnlockEntry(entry);
+      errorChain(itemRet);
+    }
+  }
+
+  assetUnlockEntry(entry);
+
+  cache->cutscene.items = cache->items;
+  cache->cutscene.itemCount = (uint8_t)itemCount;
+  cache->cutscene.pause = pause;
+  cache->cutscene.dataSize = 0;
+
+  CUTSCENE_JSON_CACHE_COUNT++;
+  *outCutscene = &cache->cutscene;
+  errorOk();
+}

src/dusk/rpg/cutscene/cutscene.h

@@ -9,18 +9,25 @@
 #include "rpg/cutscene/item/cutsceneitem.h"
 #include "rpg/cutscene/cutscenepause.h"
 
+typedef struct yyjson_val yyjson_val;
+
 typedef struct cutscene_s {
   const cutsceneitem_t *items;
   uint8_t itemCount;
   cutscenepause_t pause;
+
+  // Size in bytes of this cutscene's custom user data, carved out of
+  // CUTSCENE_SYSTEM.data while the cutscene is running.
+  size_t dataSize;
 } cutscene_t;
 
-#define CUTSCENE(NAME, PAUSE_TYPE, ...) \
+#define CUTSCENE(NAME, SIZE, PAUSE_TYPE, ...) \
   static const cutsceneitem_t CUTSCENE_##NAME##_ITEMS[] = { __VA_ARGS__ }; \
   static const cutscene_t CUTSCENE_##NAME = { \
     .items = CUTSCENE_##NAME##_ITEMS, \
     .itemCount = sizeof(CUTSCENE_##NAME##_ITEMS) / sizeof(cutsceneitem_t), \
-    .pause = CUTSCENE_PAUSE_##PAUSE_TYPE \
+    .pause = CUTSCENE_PAUSE_##PAUSE_TYPE, \
+    .dataSize = SIZE \
   };
 
 #define CUTSCENE_REFERENCE(CUTSCENE) \
@@ -29,6 +36,22 @@ typedef struct cutscene_s {
 #define CUTSCENE_TEXT(TEXT) \
   { .type = CUTSCENE_ITEM_TYPE_TEXT, .text = { .text = TEXT } }
 
+#define CUTSCENE_TEXT_MINI(TEXT, X, Y, Z, DURATION) \
+  { \
+    .type = CUTSCENE_ITEM_TYPE_TEXT_MINI, \
+    .textMini = { \
+      .text = TEXT, \
+      .position = { X, Y, Z }, \
+      .duration = DURATION \
+    } \
+  }
+
+#define CUTSCENE_TEXT_MINI_HIDE(INDEX) \
+  { \
+    .type = CUTSCENE_ITEM_TYPE_TEXT_MINI_HIDE, \
+    .textMiniHide = { .index = INDEX } \
+  }
+
 #define CUTSCENE_WAIT(WAIT) \
   { .type = CUTSCENE_ITEM_TYPE_WAIT, .wait = WAIT }
 
@@ -70,6 +93,35 @@ typedef struct cutscene_s {
     .entityRemove = { .entityIndex = ENTITY_INDEX } \
   }
 
+#define CUTSCENE_ENTITY_ADD(TYPE, X, Y, Z) \
+  { \
+    .type = CUTSCENE_ITEM_TYPE_ENTITY_ADD, \
+    .entityAdd = { .entityType = TYPE, .position = { X, Y, Z } } \
+  }
+
+#define CUTSCENE_ENTITY_TURN(ENTITY_INDEX, DIRECTION) \
+  { \
+    .type = CUTSCENE_ITEM_TYPE_ENTITY_TURN, \
+    .entityTurn = { .entityIndex = ENTITY_INDEX, .direction = DIRECTION } \
+  }
+
+// Walks ENTITY_INDEX to stand beside TARGET_ENTITY_INDEX, offset by
+// (OFFSET_X, OFFSET_Y) on the 2D plane. The destination Z is resolved
+// from nearby terrain each frame, so ramps between the two entities are
+// accounted for automatically.
+#define CUTSCENE_ENTITY_WALK_TO_ENTITY( \
+  ENTITY_INDEX, TARGET_ENTITY_INDEX, OFFSET_X, OFFSET_Y \
+) \
+  { \
+    .type = CUTSCENE_ITEM_TYPE_ENTITY_WALK_TO_ENTITY, \
+    .entityWalkToEntity = { \
+      .entityIndex = ENTITY_INDEX, \
+      .targetEntityIndex = TARGET_ENTITY_INDEX, \
+      .offsetX = OFFSET_X, \
+      .offsetY = OFFSET_Y \
+    } \
+  }
+
 #define CUTSCENE_ENTITY_TELEPORT(ENTITY_INDEX, X, Y, Z) \
   { \
     .type = CUTSCENE_ITEM_TYPE_ENTITY_TELEPORT, \
@@ -94,13 +146,31 @@ typedef struct cutscene_s {
 #define CUTSCENE_FADE_FROM_WHITE(DURATION) \
   CUTSCENE_FADE(COLOR_WHITE, COLOR_TRANSPARENT_WHITE, DURATION, EASING_LINEAR)
 
+#define CUTSCENE_EMOJI(ENTITY_INDEX, EMOJI_TYPE, DURATION) \
+  { \
+    .type = CUTSCENE_ITEM_TYPE_EMOJI, \
+    .emoji = { \
+      .entityIndex = ENTITY_INDEX, \
+      .emojiType = EMOJI_TYPE, \
+      .duration = DURATION \
+    } \
+  }
+
+// AMOUNT ranges 0 (no shake) to 4 (three tiles): 1 is half a tile, 2 is
+// a full tile, 3 is two tiles, and 4 is three tiles.
+#define CUTSCENE_SHAKE(AMOUNT, DURATION) \
+  { \
+    .type = CUTSCENE_ITEM_TYPE_SHAKE, \
+    .shake = { .amount = AMOUNT, .duration = DURATION } \
+  }
+
 #define CUTSCENE_SET_PAUSE(FLAGS) \
   { .type = CUTSCENE_ITEM_TYPE_SET_PAUSE, .setPause = (FLAGS) }
 
-#define CUTSCENE_ITEM_GIVE(ITEM_ID, QUANTITY) \
+#define CUTSCENE_ITEM_GIVE(ITEM_NAME, QUANTITY) \
   { \
     .type = CUTSCENE_ITEM_TYPE_ITEM_GIVE, \
-    .itemGive = { .item = ITEM_ID, .quantity = QUANTITY } \
+    .itemGive = { .itemName = ITEM_NAME, .quantity = QUANTITY } \
   }
 
 // Runs all listed items simultaneously and waits until all are done.
@@ -116,3 +186,164 @@ typedef struct cutscene_s {
       ) \
     } \
   }
+
+#define CUTSCENE_MAP_AREA_ADD( \
+  MIN_X, MIN_Y, MIN_Z, MAX_X, MAX_Y, MAX_Z, CALLBACK, NOTIFY, TRIGGER \
+) \
+  { \
+    .type = CUTSCENE_ITEM_TYPE_MAP_AREA_ADD, \
+    .mapAreaAdd = { \
+      .min = { MIN_X, MIN_Y, MIN_Z }, \
+      .max = { MAX_X, MAX_Y, MAX_Z }, \
+      .callback = CALLBACK, \
+      .notify = NOTIFY, \
+      .trigger = TRIGGER \
+    } \
+  }
+
+#define CUTSCENE_MAP_AREA_REMOVE(AREA_ID) \
+  { \
+    .type = CUTSCENE_ITEM_TYPE_MAP_AREA_REMOVE, \
+    .mapAreaRemove = { .areaId = AREA_ID } \
+  }
+
+// Waits until any one of the given map area IDs has its callback invoked.
+// Accepts CUTSCENE_AREA_LAST_CREATED in place of a literal area ID.
+#define CUTSCENE_MAP_AREA_WAIT(...) \
+  { \
+    .type = CUTSCENE_ITEM_TYPE_MAP_AREA_WAIT, \
+    .mapAreaWait = { \
+      .areaIds = (const uint8_t[]){ __VA_ARGS__ }, \
+      .count = (uint8_t)( \
+        sizeof((const uint8_t[]){ __VA_ARGS__ }) / sizeof(uint8_t) \
+      ) \
+    } \
+  }
+
+// Adds a map area, waits for it to be triggered once, then removes it
+// before the cutscene continues. Uses a no-op callback since the wait is
+// driven by the area's trigger count rather than callback logic.
+#define CUTSCENE_MAP_AREA_TRIGGER_ONCE( \
+  MIN_X, MIN_Y, MIN_Z, MAX_X, MAX_Y, MAX_Z, NOTIFY, TRIGGER \
+) \
+  CUTSCENE_MAP_AREA_ADD( \
+    MIN_X, MIN_Y, MIN_Z, MAX_X, MAX_Y, MAX_Z, \
+    mapAreaNoopCallback, NOTIFY, TRIGGER \
+  ), \
+  CUTSCENE_MAP_AREA_WAIT(CUTSCENE_AREA_LAST_CREATED), \
+  CUTSCENE_MAP_AREA_REMOVE(CUTSCENE_AREA_LAST_CREATED)
+
+#define CUTSCENE_JSON_NAME_MAX 32
+#define CUTSCENE_JSON_ITEM_COUNT_MAX 32
+#define CUTSCENE_JSON_WAYPOINT_COUNT_MAX 8
+#define CUTSCENE_JSON_CACHE_MAX 16
+
+// One slot of the cutsceneGetByName cache: a parsed cutscene plus the
+// backing storage its items point into (items themselves, and the
+// waypoint lists any "entityWalkTo" items reference).
+typedef struct {
+  char_t name[CUTSCENE_JSON_NAME_MAX];
+  cutscene_t cutscene;
+  cutsceneitem_t items[CUTSCENE_JSON_ITEM_COUNT_MAX];
+  worldpos_t waypoints
+    [CUTSCENE_JSON_ITEM_COUNT_MAX][CUTSCENE_JSON_WAYPOINT_COUNT_MAX];
+} cutscenejsoncacheentry_t;
+
+/**
+ * Parses a cutscene pause value ("NONE", "DEFAULT" or "ALL") from a
+ * yyjson string value.
+ *
+ * @param val The yyjson value to parse.
+ * @param outPause Output pointer, set to the parsed pause flags.
+ * @return Any error that occurs (missing/invalid/unknown value).
+ */
+errorret_t cutsceneJsonParsePause(yyjson_val *val, cutscenepause_t *outPause);
+
+/**
+ * Parses an entityIndex-shaped yyjson value - a raw number, or one of
+ * "interact", "interacted", "lastCreated" - into a raw uint8_t index or
+ * the matching CUTSCENE_ENTITY_* sentinel (see cutscenesystem.h).
+ *
+ * @param val The yyjson value to parse.
+ * @param outIndex Output pointer, set to the parsed index.
+ * @return Any error that occurs (missing/invalid/unknown value).
+ */
+errorret_t cutsceneJsonParseEntityIndex(yyjson_val *val, uint8_t *outIndex);
+
+/**
+ * Parses a [x, y, z] yyjson array into a worldpos_t.
+ *
+ * @param val The yyjson value to parse.
+ * @param outPos Output pointer, set to the parsed position.
+ * @return Any error that occurs (missing/invalid value).
+ */
+errorret_t cutsceneJsonParseWorldPos(yyjson_val *val, worldpos_t *outPos);
+
+/**
+ * Parses a single cutscene item from a yyjson object into outItem.
+ * "type" selects the item shape (required):
+ *   { "type": "text", "text": "Hello!" }
+ *   { "type": "textMini", "text": "Hi", "position": [x, y, z],
+ *     "duration": 3.0 }
+ *   { "type": "textMiniHide", "index": 0 }
+ *   { "type": "wait", "duration": 1.5 }
+ *   { "type": "entityAdd", "entityType": "npc", "position": [x, y, z] }
+ *   { "type": "entityRemove", "entityIndex": 0 }
+ *   { "type": "entityTurn", "entityIndex": 0, "direction": "south" }
+ *   { "type": "entityWalkTo", "entityIndex": 0,
+ *     "positions": [[x, y, z], ...], "walkAround": true }
+ *   { "type": "entityWalkToEntity", "entityIndex": 0,
+ *     "targetEntityIndex": 1, "offsetX": 1, "offsetY": 0 }
+ *   { "type": "entityTeleport", "entityIndex": 0, "position": [x, y, z] }
+ *   { "type": "emoji", "entityIndex": 0, "emojiType": "exclamation",
+ *     "duration": 2.0 }
+ *   { "type": "shake", "amount": 2, "duration": 0.5 }
+ *   { "type": "setPause", "pause": "ALL" }
+ * "entityIndex"/"targetEntityIndex" accept a raw number, or one of
+ * "interact", "interacted", "lastCreated" for the matching
+ * CUTSCENE_ENTITY_* sentinel. "entityType" uses the same strings as
+ * entityCreateFromJson ("player", "npc", "item"); "direction" is one of
+ * "north"/"east"/"south"/"west"; "emojiType" is "question" or
+ * "exclamation"; "pause" is "NONE", "DEFAULT" or "ALL".
+ *
+ * Not supported (would need persistent string/array storage or function
+ * pointers this parser doesn't provide): itemGive, concurrent, fade,
+ * map area items, callbacks, nested cutscene references.
+ *
+ * @param obj The yyjson object describing a single cutscene item.
+ * @param outItem Output pointer, filled with the parsed item.
+ * @param waypoints Backing storage for an "entityWalkTo" item's waypoint
+ *   list; must remain valid for as long as the parsed item is used.
+ *   Unused (may be NULL) for any other item type.
+ * @param waypointsMax Capacity of waypoints.
+ * @return Any error that occurs (missing/invalid/unknown fields).
+ */
+errorret_t cutsceneItemCreateFromJson(
+  yyjson_val *obj,
+  cutsceneitem_t *outItem,
+  worldpos_t *waypoints,
+  const uint8_t waypointsMax
+);
+
+/**
+ * Loads (or returns the cached result of an earlier load of) the named
+ * cutscene from assets/cutscene/<name>.json, parsing each entry of its
+ * "items" array with cutsceneItemCreateFromJson. Parsed once per name
+ * and cached for the lifetime of the process; holds at most
+ * CUTSCENE_JSON_CACHE_MAX distinct names, each with at most
+ * CUTSCENE_JSON_ITEM_COUNT_MAX items.
+ *
+ * File shape:
+ *   { "pause": "DEFAULT", "items": [ { "type": "text", ... }, ... ] }
+ * "pause" is optional (one of "NONE", "DEFAULT", "ALL"; defaults to
+ * "DEFAULT" when absent).
+ *
+ * @param name The cutscene's file name (without extension), under
+ *   assets/cutscene/.
+ * @param outCutscene Output pointer, set to the loaded cutscene.
+ * @return Any error that occurs (missing/malformed file, cache full,
+ *   unsupported/invalid item).
+ */
+errorret_t cutsceneGetByName(
+  const char_t *name, const cutscene_t **outCutscene
+);

src/dusk/rpg/cutscene/cutscenesystem.c

@@ -25,10 +25,19 @@ void cutsceneSystemStartCutsceneWith(
   entity_t *interact,
   entity_t *interacted
 ) {
+  assertTrue(
+    cutscene->dataSize < CUTSCENE_SYSTEM_SIZE_MAX,
+    "Cutscene data size exceeds CUTSCENE_SYSTEM_SIZE_MAX"
+  );
+
   CUTSCENE_SYSTEM.scene = cutscene;
   CUTSCENE_SYSTEM.pause = cutscene->pause;
   CUTSCENE_SYSTEM.entityInteract = interact;
   CUTSCENE_SYSTEM.entityInteracted = interacted;
+  CUTSCENE_SYSTEM.entityLastCreated = NULL;
+  CUTSCENE_SYSTEM.entityLastRef = NULL;
+  CUTSCENE_SYSTEM.areaLastCreated = CUTSCENE_AREA_LAST_CREATED;
+  CUTSCENE_SYSTEM.textMiniLastCreated = CUTSCENE_TEXT_MINI_LAST_CREATED;
   CUTSCENE_SYSTEM.currentItem = 0xFF;// Set to 0xFF so Next wraps to 0.
   cutsceneSystemNext();
 }
@@ -54,6 +63,10 @@ void cutsceneSystemNext() {
     CUTSCENE_SYSTEM.pause = CUTSCENE_PAUSE_NONE;
     CUTSCENE_SYSTEM.entityInteract = NULL;
     CUTSCENE_SYSTEM.entityInteracted = NULL;
+    CUTSCENE_SYSTEM.entityLastCreated = NULL;
+    CUTSCENE_SYSTEM.entityLastRef = NULL;
+    CUTSCENE_SYSTEM.areaLastCreated = CUTSCENE_AREA_LAST_CREATED;
+  CUTSCENE_SYSTEM.textMiniLastCreated = CUTSCENE_TEXT_MINI_LAST_CREATED;
     return;
   }
 
@@ -70,25 +83,65 @@ const cutsceneitem_t * cutsceneSystemGetCurrentItem() {
 }
 
 entity_t * cutsceneSystemGetEntity(const uint8_t entityIndex) {
+  entity_t *entity;
+
   if(entityIndex == CUTSCENE_ENTITY_INTERACT) {
     assertNotNull(
       CUTSCENE_SYSTEM.entityInteract,
       "CUTSCENE_ENTITY_INTERACT used but no interact entity is set"
     );
-    return CUTSCENE_SYSTEM.entityInteract;
-  }
-  if(entityIndex == CUTSCENE_ENTITY_INTERACTED) {
+    entity = CUTSCENE_SYSTEM.entityInteract;
+  } else if(entityIndex == CUTSCENE_ENTITY_INTERACTED) {
     assertNotNull(
       CUTSCENE_SYSTEM.entityInteracted,
       "CUTSCENE_ENTITY_INTERACTED used but no interacted entity is set"
     );
-    return CUTSCENE_SYSTEM.entityInteracted;
+    entity = CUTSCENE_SYSTEM.entityInteracted;
+  } else if(entityIndex == CUTSCENE_ENTITY_LAST_CREATED) {
+    assertNotNull(
+      CUTSCENE_SYSTEM.entityLastCreated,
+      "CUTSCENE_ENTITY_LAST_CREATED used but no entity has been created"
+    );
+    entity = CUTSCENE_SYSTEM.entityLastCreated;
+  } else if(entityIndex == CUTSCENE_ENTITY_LAST_REF) {
+    assertNotNull(
+      CUTSCENE_SYSTEM.entityLastRef,
+      "CUTSCENE_ENTITY_LAST_REF used but no entity has been referenced"
+    );
+    entity = CUTSCENE_SYSTEM.entityLastRef;
+  } else {
+    assertTrue(
+      entityIndex < ENTITY_COUNT,
+      "Entity index is out of range"
+    );
+    entity = &ENTITIES[entityIndex];
   }
-  assertTrue(
-    entityIndex < ENTITY_COUNT,
-    "Entity index is out of range"
-  );
-  return &ENTITIES[entityIndex];
+
+  CUTSCENE_SYSTEM.entityLastRef = entity;
+  return entity;
+}
+
+uint8_t cutsceneSystemGetAreaId(const uint8_t areaId) {
+  if(areaId == CUTSCENE_AREA_LAST_CREATED) {
+    assertTrue(
+      CUTSCENE_SYSTEM.areaLastCreated != CUTSCENE_AREA_LAST_CREATED,
+      "CUTSCENE_AREA_LAST_CREATED used but no map area has been created"
+    );
+    return CUTSCENE_SYSTEM.areaLastCreated;
+  }
+  return areaId;
+}
+
+uint8_t cutsceneSystemGetTextMiniId(const uint8_t index) {
+  if(index == CUTSCENE_TEXT_MINI_LAST_CREATED) {
+    assertTrue(
+      CUTSCENE_SYSTEM.textMiniLastCreated != CUTSCENE_TEXT_MINI_LAST_CREATED,
+      "CUTSCENE_TEXT_MINI_LAST_CREATED used but no mini textbox has been "
+      "shown"
+    );
+    return CUTSCENE_SYSTEM.textMiniLastCreated;
+  }
+  return index;
 }
 
 void cutsceneSystemDispose() {
@@ -97,4 +150,8 @@ void cutsceneSystemDispose() {
   CUTSCENE_SYSTEM.pause = CUTSCENE_PAUSE_NONE;
   CUTSCENE_SYSTEM.entityInteract = NULL;
   CUTSCENE_SYSTEM.entityInteracted = NULL;
+  CUTSCENE_SYSTEM.entityLastCreated = NULL;
+  CUTSCENE_SYSTEM.entityLastRef = NULL;
+  CUTSCENE_SYSTEM.areaLastCreated = CUTSCENE_AREA_LAST_CREATED;
+  CUTSCENE_SYSTEM.textMiniLastCreated = CUTSCENE_TEXT_MINI_LAST_CREATED;
 }

src/dusk/rpg/cutscene/cutscenesystem.h

@@ -10,8 +10,16 @@
 
 typedef struct entity_s entity_t;
 
-#define CUTSCENE_ENTITY_INTERACT    ((uint8_t)0xFE)
-#define CUTSCENE_ENTITY_INTERACTED  ((uint8_t)0xFD)
+#define CUTSCENE_ENTITY_INTERACT      ((uint8_t)0xFE)
+#define CUTSCENE_ENTITY_INTERACTED    ((uint8_t)0xFD)
+#define CUTSCENE_ENTITY_LAST_CREATED  ((uint8_t)0xFC)
+#define CUTSCENE_ENTITY_LAST_REF      ((uint8_t)0xFB)
+#define CUTSCENE_AREA_LAST_CREATED    ((uint8_t)0xFF)
+#define CUTSCENE_TEXT_MINI_LAST_CREATED ((uint8_t)0xFA)
+
+// Maximum number of bytes a running cutscene may request via
+// cutscene_t.dataSize.
+#define CUTSCENE_SYSTEM_SIZE_MAX 8192
 
 typedef struct {
   const cutscene_t *scene;
@@ -19,9 +27,17 @@ typedef struct {
   cutscenepause_t pause;
   entity_t *entityInteract;
   entity_t *entityInteracted;
+  entity_t *entityLastCreated;
+  entity_t *entityLastRef;
+  uint8_t areaLastCreated;
+  uint8_t textMiniLastCreated;
 
   // Data (used by the current item).
   cutsceneitemdata_t data;
+
+  // Custom user data for the running cutscene, sized per-scene by
+  // cutscene_t.dataSize.
+  uint8_t userData[CUTSCENE_SYSTEM_SIZE_MAX];
 } cutscenesystem_t;
 
 extern cutscenesystem_t CUTSCENE_SYSTEM;
@@ -53,7 +69,9 @@ void cutsceneSystemStartCutsceneWith(
 
 /**
  * Resolves a raw entity index (or sentinel) to an entity pointer.
- * Handles CUTSCENE_ENTITY_INTERACT and CUTSCENE_ENTITY_INTERACTED.
+ * Handles CUTSCENE_ENTITY_INTERACT, CUTSCENE_ENTITY_INTERACTED,
+ * CUTSCENE_ENTITY_LAST_CREATED and CUTSCENE_ENTITY_LAST_REF.
+ * Updates CUTSCENE_SYSTEM.entityLastRef to the resolved entity.
  * Asserts the resolved entity is within bounds.
  *
  * @param entityIndex Raw entity index or sentinel value.
@@ -61,6 +79,24 @@ void cutsceneSystemStartCutsceneWith(
  */
 entity_t * cutsceneSystemGetEntity(const uint8_t entityIndex);
 
+/**
+ * Resolves a raw map area ID (or CUTSCENE_AREA_LAST_CREATED sentinel) to
+ * a concrete map area ID.
+ *
+ * @param areaId Raw map area ID or sentinel value.
+ * @returns The resolved map area ID.
+ */
+uint8_t cutsceneSystemGetAreaId(const uint8_t areaId);
+
+/**
+ * Resolves a raw mini textbox slot index (or CUTSCENE_TEXT_MINI_LAST_CREATED
+ * sentinel) to a concrete UI_TEXTBOX_MINI_LIST slot index.
+ *
+ * @param index Raw slot index or sentinel value.
+ * @returns The resolved slot index.
+ */
+uint8_t cutsceneSystemGetTextMiniId(const uint8_t index);
+
 /**
  * Advance to the next item in the cutscene.
  */

src/dusk/rpg/cutscene/item/CMakeLists.txt

@@ -12,4 +12,6 @@ target_sources(${DUSK_LIBRARY_TARGET_NAME}
 add_subdirectory(control)
 add_subdirectory(entity)
 add_subdirectory(item)
+add_subdirectory(maparea)
 add_subdirectory(ui)
+add_subdirectory(battle)

src/dusk/rpg/cutscene/item/battle/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
+    cutscenestartbattle.c
+)

src/dusk/rpg/cutscene/item/battle/cutscenestartbattle.c

@@ -0,0 +1,71 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#include "rpg/cutscene/item/cutsceneitem.h"
+#include "rpg/battle/party.h"
+#include "scene/scene.h"
+
+void cutsceneStartBattleStart(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+) {
+  const cutscenestartbattle_t *config = &item->startBattle;
+
+  battleInit();
+
+  for(uint8_t i = 0; i < PARTY_ACTIVE_SIZE_MAX; i++) {
+    battlefighter_t *member = partyGetOrderMember(i);
+    if(member == NULL) continue;
+
+    battlefighter_t *fighter = battleAddFighter(
+      BATTLE_FIGHTER_TEAM_ALLY, BATTLE_FIGHTER_CONTROLLER_PLAYER,
+      member->stats, member->healthMax, member->mpMax
+    );
+    if(fighter == NULL) continue;
+
+    fighter->health = member->health;
+    fighter->mp = member->mp;
+    fighter->status = member->status;
+  }
+
+  for(uint8_t i = 0; i < config->enemyCount; i++) {
+    const cutscenestartbattleenemy_t *enemy = &config->enemies[i];
+    battleAddFighter(
+      BATTLE_FIGHTER_TEAM_ENEMY, BATTLE_FIGHTER_CONTROLLER_AI,
+      enemy->stats, enemy->healthMax, enemy->mpMax
+    );
+  }
+
+  battleStart(config->encounterType, config->fleeAvailable);
+  sceneSet(SCENE_TYPE_BATTLE);
+}
+
+bool_t cutsceneStartBattleUpdate(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+) {
+  if(BATTLE.result == BATTLE_RESULT_NONE) return false;
+
+  // Sync ally HP/MP back to the persistent party roster. Relies on
+  // ally fighters having been added to BATTLE.fighters in the same
+  // order partyGetOrderMember() iterates, starting at index 0 (see
+  // cutsceneStartBattleStart).
+  uint8_t allySlot = 0;
+  for(uint8_t i = 0; i < PARTY_ACTIVE_SIZE_MAX; i++) {
+    battlefighter_t *member = partyGetOrderMember(i);
+    if(member == NULL) continue;
+
+    battlefighter_t *fighter = &BATTLE.fighters[allySlot++];
+    member->health = fighter->health;
+    member->mp = fighter->mp;
+    member->status = fighter->status;
+  }
+
+  sceneSet(SCENE_TYPE_OVERWORLD);
+  battleDispose();
+  return true;
+}

src/dusk/rpg/cutscene/item/battle/cutscenestartbattle.h

@@ -0,0 +1,53 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#pragma once
+#include "rpg/battle/battle.h"
+
+#define CUTSCENE_START_BATTLE_ENEMY_COUNT_MAX 4
+
+typedef struct {
+  battlefighterstats_t stats;
+  uint16_t healthMax;
+  uint16_t mpMax;
+} cutscenestartbattleenemy_t;
+
+typedef struct cutsceneitem_s cutsceneitem_t;
+typedef union cutsceneitemdata_u cutsceneitemdata_t;
+
+typedef struct {
+  battleencountertype_t encounterType;
+  bool_t fleeAvailable;
+  uint8_t enemyCount;
+  cutscenestartbattleenemy_t enemies[CUTSCENE_START_BATTLE_ENEMY_COUNT_MAX];
+} cutscenestartbattle_t;
+
+/**
+ * Starts a battle: seeds BATTLE with the party's active order members
+ * and the item's configured enemies, then switches to the battle
+ * scene.
+ *
+ * @param item The cutscene item.
+ * @param data Runtime data storage.
+ */
+void cutsceneStartBattleStart(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+);
+
+/**
+ * Waits for the battle to produce a result, syncs ally HP/MP back to
+ * the party roster, then returns to the overworld scene.
+ *
+ * @param item The cutscene item.
+ * @param data Runtime data storage.
+ * @returns true once the battle has ended.
+ */
+bool_t cutsceneStartBattleUpdate(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+);

src/dusk/rpg/cutscene/item/cutscenecallback.c

@@ -6,12 +6,13 @@
  */
 
 #include "cutsceneitem.h"
+#include "rpg/cutscene/cutscenesystem.h"
 
 void cutsceneCallbackStart(
   const cutsceneitem_t *item,
   cutsceneitemdata_t *data
 ) {
-  if(item->callback != NULL) item->callback();
+  if(item->callback != NULL) item->callback(CUTSCENE_SYSTEM.userData);
 }
 
 bool_t cutsceneCallbackUpdate(

src/dusk/rpg/cutscene/item/cutscenecallback.h

@@ -11,7 +11,7 @@
 typedef struct cutsceneitem_s cutsceneitem_t;
 typedef union cutsceneitemdata_u cutsceneitemdata_t;
 
-typedef void (*cutscenecallback_t)(void);
+typedef void (*cutscenecallback_t)(void *userData);
 
 /**
  * Starts a callback item (invokes the callback immediately).

src/dusk/rpg/cutscene/item/cutsceneitem.c

@@ -7,90 +7,146 @@
 
 #include "rpg/cutscene/cutscenesystem.h"
 
+cutsceneitemcallbacks_t CUTSCENE_ITEM_CALLBACKS[CUTSCENE_ITEM_TYPE_COUNT] = {
+  [CUTSCENE_ITEM_TYPE_NULL] = { 0 },
+
+  [CUTSCENE_ITEM_TYPE_TEXT] = {
+    .init = cutsceneTextStart,
+    .update = cutsceneTextUpdate
+  },
+
+  [CUTSCENE_ITEM_TYPE_TEXT_MINI] = {
+    .init = cutsceneTextMiniStart,
+    .update = cutsceneTextMiniUpdate
+  },
+
+  [CUTSCENE_ITEM_TYPE_TEXT_MINI_HIDE] = {
+    .init = cutsceneTextMiniHideStart,
+    .update = cutsceneTextMiniHideUpdate
+  },
+
+  [CUTSCENE_ITEM_TYPE_CALLBACK] = {
+    .init = cutsceneCallbackStart,
+    .update = cutsceneCallbackUpdate
+  },
+
+  [CUTSCENE_ITEM_TYPE_WAIT] = {
+    .init = cutsceneWaitStart,
+    .update = cutsceneWaitUpdate
+  },
+
+  [CUTSCENE_ITEM_TYPE_CUTSCENE] = {
+    .init = cutsceneCutsceneStart,
+    .update = cutsceneCutsceneUpdate
+  },
+
+  [CUTSCENE_ITEM_TYPE_ENTITY_TELEPORT] = {
+    .init = cutsceneEntityTeleportStart,
+    .update = cutsceneEntityTeleportUpdate
+  },
+
+  [CUTSCENE_ITEM_TYPE_ENTITY_WALK_TO] = {
+    .init = cutsceneEntityWalkToStart,
+    .update = cutsceneEntityWalkToUpdate
+  },
+
+  [CUTSCENE_ITEM_TYPE_FADE] = {
+    .init = cutsceneFadeStart,
+    .update = cutsceneFadeUpdate
+  },
+
+  [CUTSCENE_ITEM_TYPE_SET_PAUSE] = {
+    .init = cutsceneSetPauseStart,
+    .update = cutsceneSetPauseUpdate
+  },
+
+  [CUTSCENE_ITEM_TYPE_CONCURRENT] = {
+    .init = cutsceneConcurrentStart,
+    .update = cutsceneConcurrentUpdate
+  },
+
+  [CUTSCENE_ITEM_TYPE_ITEM_GIVE] = {
+    .init = cutsceneItemGiveStart,
+    .update = cutsceneItemGiveUpdate
+  },
+
+  [CUTSCENE_ITEM_TYPE_ENTITY_REMOVE] = {
+    .init = cutsceneEntityRemoveStart,
+    .update = cutsceneEntityRemoveUpdate
+  },
+
+  [CUTSCENE_ITEM_TYPE_ENTITY_ADD] = {
+    .init = cutsceneEntityAddStart,
+    .update = cutsceneEntityAddUpdate
+  },
+
+  [CUTSCENE_ITEM_TYPE_ENTITY_TURN] = {
+    .init = cutsceneEntityTurnStart,
+    .update = cutsceneEntityTurnUpdate
+  },
+
+  [CUTSCENE_ITEM_TYPE_ENTITY_WALK_TO_ENTITY] = {
+    .init = cutsceneEntityWalkToEntityStart,
+    .update = cutsceneEntityWalkToEntityUpdate
+  },
+
+  [CUTSCENE_ITEM_TYPE_MAP_AREA_ADD] = {
+    .init = cutsceneMapAreaAddStart,
+    .update = cutsceneMapAreaAddUpdate
+  },
+
+  [CUTSCENE_ITEM_TYPE_MAP_AREA_REMOVE] = {
+    .init = cutsceneMapAreaRemoveStart,
+    .update = cutsceneMapAreaRemoveUpdate
+  },
+
+  [CUTSCENE_ITEM_TYPE_MAP_AREA_WAIT] = {
+    .init = cutsceneMapAreaWaitStart,
+    .update = cutsceneMapAreaWaitUpdate
+  },
+
+  [CUTSCENE_ITEM_TYPE_START_BATTLE] = {
+    .init = cutsceneStartBattleStart,
+    .update = cutsceneStartBattleUpdate
+  },
+
+  [CUTSCENE_ITEM_TYPE_EMOJI] = {
+    .init = cutsceneEmojiStart,
+    .update = cutsceneEmojiUpdate
+  },
+
+  [CUTSCENE_ITEM_TYPE_SHAKE] = {
+    .init = cutsceneShakeStart,
+    .update = cutsceneShakeUpdate
+  }
+};
+
 void cutsceneItemStart(const cutsceneitem_t *item, cutsceneitemdata_t *data) {
-  switch(item->type) {
-    case CUTSCENE_ITEM_TYPE_TEXT:
-      cutsceneTextStart(item, data);
-      break;
-
-    case CUTSCENE_ITEM_TYPE_CALLBACK:
-      cutsceneCallbackStart(item, data);
-      break;
-
-    case CUTSCENE_ITEM_TYPE_WAIT:
-      cutsceneWaitStart(item, data);
-      break;
-
-    case CUTSCENE_ITEM_TYPE_CUTSCENE:
-      if(item->cutscene != NULL) cutsceneSystemStartCutscene(item->cutscene);
-      break;
-
-    case CUTSCENE_ITEM_TYPE_ENTITY_TELEPORT:
-      cutsceneEntityTeleportStart(item, data);
-      break;
-
-    case CUTSCENE_ITEM_TYPE_ENTITY_WALK_TO:
-      cutsceneEntityWalkToStart(item, data);
-      break;
-
-    case CUTSCENE_ITEM_TYPE_FADE:
-      cutsceneFadeStart(item, data);
-      break;
-
-    case CUTSCENE_ITEM_TYPE_SET_PAUSE:
-      cutsceneSetPauseStart(item, data);
-      break;
-
-    case CUTSCENE_ITEM_TYPE_CONCURRENT:
-      cutsceneConcurrentStart(item, data);
-      break;
-
-    case CUTSCENE_ITEM_TYPE_ITEM_GIVE:
-      cutsceneItemGiveStart(item, data);
-      break;
-
-    case CUTSCENE_ITEM_TYPE_ENTITY_REMOVE:
-      cutsceneEntityRemoveStart(item, data);
-      break;
-
-    default:
-      break;
-  }
+  cutsceneiteminitcallback_t *init = CUTSCENE_ITEM_CALLBACKS[item->type].init;
+  if(init != NULL) init(item, data);
 }
 
-bool_t cutsceneItemUpdate(const cutsceneitem_t *item, cutsceneitemdata_t *data) {
-  switch(item->type) {
-    case CUTSCENE_ITEM_TYPE_TEXT:
-      return cutsceneTextUpdate(item, data);
+bool_t cutsceneItemUpdate(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+) {
+  cutsceneitemupdatecallback_t *update =
+    CUTSCENE_ITEM_CALLBACKS[item->type].update;
+  if(update == NULL) return false;
 
-    case CUTSCENE_ITEM_TYPE_CALLBACK:
-      return cutsceneCallbackUpdate(item, data);
-
-    case CUTSCENE_ITEM_TYPE_WAIT:
-      return cutsceneWaitUpdate(item, data);
-
-    case CUTSCENE_ITEM_TYPE_ENTITY_TELEPORT:
-      return cutsceneEntityTeleportUpdate(item, data);
-
-    case CUTSCENE_ITEM_TYPE_ENTITY_WALK_TO:
-      return cutsceneEntityWalkToUpdate(item, data);
-
-    case CUTSCENE_ITEM_TYPE_FADE:
-      return cutsceneFadeUpdate(item, data);
-
-    case CUTSCENE_ITEM_TYPE_SET_PAUSE:
-      return cutsceneSetPauseUpdate(item, data);
-
-    case CUTSCENE_ITEM_TYPE_CONCURRENT:
-      return cutsceneConcurrentUpdate(item, data);
-
-    case CUTSCENE_ITEM_TYPE_ITEM_GIVE:
-      return cutsceneItemGiveUpdate(item, data);
-
-    case CUTSCENE_ITEM_TYPE_ENTITY_REMOVE:
-      return cutsceneEntityRemoveUpdate(item, data);
-
-    default:
-      return false;
-  }
+  return update(item, data);
+}
+
+void cutsceneCutsceneStart(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+) {
+  if(item->cutscene != NULL) cutsceneSystemStartCutscene(item->cutscene);
+}
+
+bool_t cutsceneCutsceneUpdate(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+) {
+  return false;
 }

src/dusk/rpg/cutscene/item/cutsceneitem.h

@@ -13,15 +13,29 @@
 #include "entity/cutsceneentityteleport.h"
 #include "entity/cutsceneentitywalkto.h"
 #include "entity/cutsceneentityremove.h"
+#include "entity/cutsceneentityadd.h"
+#include "entity/cutsceneentityturn.h"
+#include "entity/cutsceneentitywalktoentity.h"
 #include "ui/cutscenetext.h"
+#include "ui/cutscenetextmini.h"
+#include "ui/cutscenetextminihide.h"
 #include "ui/cutscenefade.h"
+#include "ui/cutsceneemoji.h"
+#include "ui/cutsceneshake.h"
 #include "item/cutsceneitemgive.h"
+#include "maparea/cutscenemapareaadd.h"
+#include "maparea/cutscenemaparearemove.h"
+#include "maparea/cutscenemapareawait.h"
+#include "battle/cutscenestartbattle.h"
 
 typedef struct cutscene_s cutscene_t;
 
 typedef enum {
   CUTSCENE_ITEM_TYPE_NULL,
+
   CUTSCENE_ITEM_TYPE_TEXT,
+  CUTSCENE_ITEM_TYPE_TEXT_MINI,
+  CUTSCENE_ITEM_TYPE_TEXT_MINI_HIDE,
   CUTSCENE_ITEM_TYPE_CALLBACK,
   CUTSCENE_ITEM_TYPE_WAIT,
   CUTSCENE_ITEM_TYPE_CUTSCENE,
@@ -31,7 +45,18 @@ typedef enum {
   CUTSCENE_ITEM_TYPE_SET_PAUSE,
   CUTSCENE_ITEM_TYPE_CONCURRENT,
   CUTSCENE_ITEM_TYPE_ITEM_GIVE,
-  CUTSCENE_ITEM_TYPE_ENTITY_REMOVE
+  CUTSCENE_ITEM_TYPE_ENTITY_REMOVE,
+  CUTSCENE_ITEM_TYPE_ENTITY_ADD,
+  CUTSCENE_ITEM_TYPE_ENTITY_TURN,
+  CUTSCENE_ITEM_TYPE_ENTITY_WALK_TO_ENTITY,
+  CUTSCENE_ITEM_TYPE_MAP_AREA_ADD,
+  CUTSCENE_ITEM_TYPE_MAP_AREA_REMOVE,
+  CUTSCENE_ITEM_TYPE_MAP_AREA_WAIT,
+  CUTSCENE_ITEM_TYPE_START_BATTLE,
+  CUTSCENE_ITEM_TYPE_EMOJI,
+  CUTSCENE_ITEM_TYPE_SHAKE,
+
+  CUTSCENE_ITEM_TYPE_COUNT
 } cutsceneitemtype_t;
 
 struct cutsceneitem_s {
@@ -39,6 +64,8 @@ struct cutsceneitem_s {
 
   union {
     cutscenetext_t text;
+    cutscenetextmini_t textMini;
+    cutscenetextminihide_t textMiniHide;
     cutscenecallback_t callback;
     cutscenewait_t wait;
     const cutscene_t *cutscene;
@@ -49,6 +76,15 @@ struct cutsceneitem_s {
     cutsceneconcurrent_t concurrent;
     cutsceneitemgive_t itemGive;
     cutsceneentityremove_t entityRemove;
+    cutsceneentityadd_t entityAdd;
+    cutsceneentityturn_t entityTurn;
+    cutsceneentitywalktoentity_t entityWalkToEntity;
+    cutscenemapareaadd_t mapAreaAdd;
+    cutscenemaparearemove_t mapAreaRemove;
+    cutscenemapareawait_t mapAreaWait;
+    cutscenestartbattle_t startBattle;
+    cutsceneemoji_t emoji;
+    cutsceneshake_t shake;
   };
 };
 
@@ -56,8 +92,27 @@ typedef union cutsceneitemdata_u {
   cutscenewaitdata_t wait;
   cutsceneentitywalktodata_t entityWalkTo;
   cutsceneconcurrentdata_t concurrent;
+  cutscenemapareawaitdata_t mapAreaWait;
 } cutsceneitemdata_t;
 
+typedef void (cutsceneiteminitcallback_t)(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+);
+
+typedef bool_t (cutsceneitemupdatecallback_t)(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+);
+
+typedef struct {
+  cutsceneiteminitcallback_t *init;
+  cutsceneitemupdatecallback_t *update;
+} cutsceneitemcallbacks_t;
+
+extern cutsceneitemcallbacks_t
+ CUTSCENE_ITEM_CALLBACKS[CUTSCENE_ITEM_TYPE_COUNT];
+
 /**
  * Start the given cutscene item.
  *
@@ -80,3 +135,29 @@ bool_t cutsceneItemUpdate(
   const cutsceneitem_t *item,
   cutsceneitemdata_t *data
 );
+
+/**
+ * Starts a nested-cutscene item, handing control over to the
+ * referenced cutscene.
+ *
+ * @param item The cutscene item.
+ * @param data Runtime data storage.
+ */
+void cutsceneCutsceneStart(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+);
+
+/**
+ * Updates a nested-cutscene item. By the time this would run, control
+ * has already moved on to the referenced cutscene, so this always
+ * reports incomplete.
+ *
+ * @param item The cutscene item.
+ * @param data Runtime data storage.
+ * @returns false always.
+ */
+bool_t cutsceneCutsceneUpdate(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+);

src/dusk/rpg/cutscene/item/entity/CMakeLists.txt

@@ -8,4 +8,7 @@ target_sources(${DUSK_LIBRARY_TARGET_NAME}
     cutsceneentityteleport.c
     cutsceneentitywalkto.c
     cutsceneentityremove.c
+    cutsceneentityadd.c
+    cutsceneentityturn.c
+    cutsceneentitywalktoentity.c
 )

src/dusk/rpg/cutscene/item/entity/cutsceneentityadd.c

@@ -0,0 +1,33 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#include "rpg/cutscene/item/cutsceneitem.h"
+#include "rpg/cutscene/cutscenesystem.h"
+#include "rpg/entity/entity.h"
+#include "assert/assert.h"
+
+void cutsceneEntityAddStart(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+) {
+  uint8_t entIndex = entityGetAvailable();
+  assertTrue(entIndex != 0xFF, "No available entity slots for CUTSCENE_ENTITY_ADD");
+
+  entity_t *entity = &ENTITIES[entIndex];
+  entityInit(entity, item->entityAdd.entityType);
+  entityPositionSet(entity, item->entityAdd.position);// Also assigns chunk.
+
+  CUTSCENE_SYSTEM.entityLastCreated = entity;
+  CUTSCENE_SYSTEM.entityLastRef = entity;
+}
+
+bool_t cutsceneEntityAddUpdate(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+) {
+  return true;
+}

src/dusk/rpg/cutscene/item/entity/cutsceneentityadd.h

@@ -0,0 +1,41 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#pragma once
+#include "rpg/entity/entitytype.h"
+#include "rpg/overworld/worldpos.h"
+
+typedef struct cutsceneitem_s cutsceneitem_t;
+typedef union cutsceneitemdata_u cutsceneitemdata_t;
+
+typedef struct {
+  entitytype_t entityType;
+  worldpos_t position;
+} cutsceneentityadd_t;
+
+/**
+ * Starts an entity add step (spawns the entity into the world immediately).
+ *
+ * @param item The cutscene item.
+ * @param data Runtime data storage.
+ */
+void cutsceneEntityAddStart(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+);
+
+/**
+ * Updates an entity add step (always completes immediately).
+ *
+ * @param item The cutscene item.
+ * @param data Runtime data storage.
+ * @returns true always.
+ */
+bool_t cutsceneEntityAddUpdate(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+);

src/dusk/rpg/cutscene/item/entity/cutsceneentityturn.c

@@ -0,0 +1,30 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#include "rpg/cutscene/item/cutsceneitem.h"
+#include "rpg/cutscene/cutscenesystem.h"
+#include "rpg/entity/entity.h"
+
+void cutsceneEntityTurnStart(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+) {
+}
+
+bool_t cutsceneEntityTurnUpdate(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+) {
+  entity_t *entity = cutsceneSystemGetEntity(item->entityTurn.entityIndex);
+  if(
+    entity->direction == item->entityTurn.direction &&
+    entity->animation == ENTITY_ANIM_IDLE
+  ) return true;
+
+  entityTurn(entity, item->entityTurn.direction);
+  return false;
+}

src/dusk/rpg/cutscene/item/entity/cutsceneentityturn.h

@@ -0,0 +1,42 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#pragma once
+#include "rpg/entity/entitydir.h"
+
+typedef struct cutsceneitem_s cutsceneitem_t;
+typedef union cutsceneitemdata_u cutsceneitemdata_t;
+
+typedef struct {
+  uint8_t entityIndex;
+  entitydir_t direction;
+} cutsceneentityturn_t;
+
+/**
+ * Starts an entity turn step. The turn itself is driven from Update, since
+ * the entity may still be finishing a previous action.
+ *
+ * @param item The cutscene item.
+ * @param data Runtime data storage.
+ */
+void cutsceneEntityTurnStart(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+);
+
+/**
+ * Updates an entity turn step, retrying entityTurn until it takes effect
+ * and its animation completes.
+ *
+ * @param item The cutscene item.
+ * @param data Runtime data storage.
+ * @returns true once the entity is idle and facing the target direction.
+ */
+bool_t cutsceneEntityTurnUpdate(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+);

src/dusk/rpg/cutscene/item/entity/cutsceneentitywalktoentity.c

@@ -0,0 +1,41 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#include "rpg/cutscene/item/cutsceneitem.h"
+#include "rpg/cutscene/cutscenesystem.h"
+#include "rpg/entity/entity.h"
+#include "rpg/entity/entitypathstep.h"
+#include "rpg/overworld/chunk.h"
+
+void cutsceneEntityWalkToEntityStart(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+) {
+}
+
+bool_t cutsceneEntityWalkToEntityUpdate(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+) {
+  entity_t *entity = cutsceneSystemGetEntity(
+    item->entityWalkToEntity.entityIndex
+  );
+  entity_t *target = cutsceneSystemGetEntity(
+    item->entityWalkToEntity.targetEntityIndex
+  );
+
+  worldpos_t dest = {
+    .x = (worldunit_t)(target->position.x + item->entityWalkToEntity.offsetX),
+    .y = (worldunit_t)(target->position.y + item->entityWalkToEntity.offsetY),
+    .z = target->position.z
+  };
+
+  worldunit_t z;
+  if(chunkGetWalkableZNear(dest.x, dest.y, target->position.z, &z)) dest.z = z;
+
+  return entityPathStep(entity, dest, true);
+}

src/dusk/rpg/cutscene/item/entity/cutsceneentitywalktoentity.h

@@ -0,0 +1,46 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#pragma once
+#include "rpg/overworld/worldpos.h"
+
+typedef struct cutsceneitem_s cutsceneitem_t;
+typedef union cutsceneitemdata_u cutsceneitemdata_t;
+
+typedef struct {
+  uint8_t entityIndex;
+  uint8_t targetEntityIndex;
+  worldunit_t offsetX;
+  worldunit_t offsetY;
+} cutsceneentitywalktoentity_t;
+
+/**
+ * Starts an entity walk-to-entity item. No setup is needed, the destination
+ * is recomputed from the target's live position every Update.
+ *
+ * @param item The cutscene item.
+ * @param data Runtime data storage.
+ */
+void cutsceneEntityWalkToEntityStart(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+);
+
+/**
+ * Updates an entity walk-to-entity item. Re-reads the target entity's
+ * current position each frame, applies the X/Y offset, resolves the
+ * destination Z from nearby terrain (to account for ramps), and steps
+ * the entity toward it.
+ *
+ * @param item The cutscene item.
+ * @param data Runtime data storage.
+ * @returns true once the entity has reached the target's side.
+ */
+bool_t cutsceneEntityWalkToEntityUpdate(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+);

src/dusk/rpg/cutscene/item/item/cutsceneitemgive.c

@@ -6,25 +6,16 @@
  */
 
 #include "rpg/cutscene/item/cutsceneitem.h"
-#include "rpg/item/backpack.h"
-#include "ui/rpg/uitextboxmain.h"
-#include "util/string.h"
+#include "rpg/item/item.h"
+#include "rpg/item/itemgive.h"
+#include "ui/rpg/textbox/uitextboxmain.h"
 
 void cutsceneItemGiveStart(
   const cutsceneitem_t *item,
   cutsceneitemdata_t *data
 ) {
-  backpackAdd(item->itemGive.item, item->itemGive.quantity);
-
-  char_t msg[CUTSCENE_TEXT_MAX_CHARS];
-  stringFormat(
-    msg,
-    CUTSCENE_TEXT_MAX_CHARS - 1,
-    "Received %s x%u",
-    ITEMS[item->itemGive.item].name,
-    (uint32_t)item->itemGive.quantity
-  );
-  uiTextboxMainSetText(msg);
+  itemid_t itemId = itemGetIdByName(item->itemGive.itemName);
+  itemGive(itemId, item->itemGive.quantity);
 }
 
 bool_t cutsceneItemGiveUpdate(

src/dusk/rpg/cutscene/item/item/cutsceneitemgive.h

@@ -6,13 +6,13 @@
  */
 
 #pragma once
-#include "rpg/item/item.h"
+#include "dusk.h"
 
 typedef struct cutsceneitem_s cutsceneitem_t;
 typedef union cutsceneitemdata_u cutsceneitemdata_t;
 
 typedef struct {
-  itemid_t item;
+  const char_t *itemName;
   uint8_t quantity;
 } cutsceneitemgive_t;
 

src/dusk/rpg/cutscene/item/maparea/CMakeLists.txt

@@ -0,0 +1,11 @@
+# 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
+    cutscenemapareaadd.c
+    cutscenemaparearemove.c
+    cutscenemapareawait.c
+)

src/dusk/rpg/cutscene/item/maparea/cutscenemapareaadd.c

@@ -0,0 +1,29 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#include "rpg/cutscene/item/cutsceneitem.h"
+#include "rpg/cutscene/cutscenesystem.h"
+
+void cutsceneMapAreaAddStart(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+) {
+  CUTSCENE_SYSTEM.areaLastCreated = mapAreaAdd(
+    item->mapAreaAdd.min,
+    item->mapAreaAdd.max,
+    item->mapAreaAdd.callback,
+    item->mapAreaAdd.notify,
+    item->mapAreaAdd.trigger
+  );
+}
+
+bool_t cutsceneMapAreaAddUpdate(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+) {
+  return true;
+}

src/dusk/rpg/cutscene/item/maparea/cutscenemapareaadd.h

@@ -0,0 +1,44 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#pragma once
+#include "rpg/overworld/maparea.h"
+
+typedef struct cutsceneitem_s cutsceneitem_t;
+typedef union cutsceneitemdata_u cutsceneitemdata_t;
+
+typedef struct {
+  worldpos_t min;
+  worldpos_t max;
+  mapareacallback_t callback;
+  uint8_t notify;
+  uint8_t trigger;
+} cutscenemapareaadd_t;
+
+/**
+ * Starts a map area add step (adds the area immediately, storing its ID
+ * in CUTSCENE_SYSTEM.areaLastCreated).
+ *
+ * @param item The cutscene item.
+ * @param data Runtime data storage.
+ */
+void cutsceneMapAreaAddStart(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+);
+
+/**
+ * Updates a map area add step (always completes immediately).
+ *
+ * @param item The cutscene item.
+ * @param data Runtime data storage.
+ * @returns true always.
+ */
+bool_t cutsceneMapAreaAddUpdate(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+);

src/dusk/rpg/cutscene/item/maparea/cutscenemaparearemove.c

@@ -0,0 +1,24 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#include "rpg/cutscene/item/cutsceneitem.h"
+#include "rpg/cutscene/cutscenesystem.h"
+#include "rpg/overworld/maparea.h"
+
+void cutsceneMapAreaRemoveStart(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+) {
+  mapAreaRemove(cutsceneSystemGetAreaId(item->mapAreaRemove.areaId));
+}
+
+bool_t cutsceneMapAreaRemoveUpdate(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+) {
+  return true;
+}

src/dusk/rpg/cutscene/item/maparea/cutscenemaparearemove.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 "dusk.h"
+
+typedef struct cutsceneitem_s cutsceneitem_t;
+typedef union cutsceneitemdata_u cutsceneitemdata_t;
+
+typedef struct {
+  uint8_t areaId;
+} cutscenemaparearemove_t;
+
+/**
+ * Starts a map area remove step (removes the area immediately). Accepts
+ * CUTSCENE_AREA_LAST_CREATED in place of a literal area ID.
+ *
+ * @param item The cutscene item.
+ * @param data Runtime data storage.
+ */
+void cutsceneMapAreaRemoveStart(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+);
+
+/**
+ * Updates a map area remove step (always completes immediately).
+ *
+ * @param item The cutscene item.
+ * @param data Runtime data storage.
+ * @returns true always.
+ */
+bool_t cutsceneMapAreaRemoveUpdate(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+);

src/dusk/rpg/cutscene/item/maparea/cutscenemapareawait.c

@@ -0,0 +1,40 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#include "rpg/cutscene/item/cutsceneitem.h"
+#include "rpg/cutscene/cutscenesystem.h"
+#include "rpg/overworld/maparea.h"
+#include "assert/assert.h"
+
+void cutsceneMapAreaWaitStart(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+) {
+  assertTrue(
+    item->mapAreaWait.count <= CUTSCENE_MAP_AREA_WAIT_MAX,
+    "Too many areas in CUTSCENE_MAP_AREA_WAIT"
+  );
+
+  for(uint8_t i = 0; i < item->mapAreaWait.count; i++) {
+    uint8_t areaId = cutsceneSystemGetAreaId(item->mapAreaWait.areaIds[i]);
+    data->mapAreaWait.baseline[i] = MAP_AREAS[areaId].triggerCount;
+  }
+}
+
+bool_t cutsceneMapAreaWaitUpdate(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+) {
+  for(uint8_t i = 0; i < item->mapAreaWait.count; i++) {
+    uint8_t areaId = cutsceneSystemGetAreaId(item->mapAreaWait.areaIds[i]);
+    if(MAP_AREAS[areaId].triggerCount != data->mapAreaWait.baseline[i]) {
+      return true;
+    }
+  }
+
+  return false;
+}

src/dusk/rpg/cutscene/item/maparea/cutscenemapareawait.h

@@ -0,0 +1,49 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#pragma once
+#include "dusk.h"
+
+typedef struct cutsceneitem_s cutsceneitem_t;
+typedef union cutsceneitemdata_u cutsceneitemdata_t;
+
+/** Maximum number of areas a single CUTSCENE_MAP_AREA_WAIT may watch. */
+#define CUTSCENE_MAP_AREA_WAIT_MAX 4
+
+typedef struct {
+  const uint8_t *areaIds;
+  uint8_t count;
+} cutscenemapareawait_t;
+
+typedef struct {
+  uint32_t baseline[CUTSCENE_MAP_AREA_WAIT_MAX];
+} cutscenemapareawaitdata_t;
+
+/**
+ * Starts a map area wait step, snapshotting each watched area's current
+ * trigger count.
+ *
+ * @param item The cutscene item.
+ * @param data Runtime data storage.
+ */
+void cutsceneMapAreaWaitStart(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+);
+
+/**
+ * Updates a map area wait step, completing once any watched area's
+ * trigger count has changed since Start (i.e. its callback fired).
+ *
+ * @param item The cutscene item.
+ * @param data Runtime data storage.
+ * @returns true once any watched area has been triggered.
+ */
+bool_t cutsceneMapAreaWaitUpdate(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+);

src/dusk/rpg/cutscene/item/ui/CMakeLists.txt

@@ -6,5 +6,9 @@
 target_sources(${DUSK_LIBRARY_TARGET_NAME}
   PUBLIC
     cutscenetext.c
+    cutscenetextmini.c
+    cutscenetextminihide.c
     cutscenefade.c
+    cutsceneemoji.c
+    cutsceneshake.c
 )

src/dusk/rpg/cutscene/item/ui/cutsceneemoji.c

@@ -0,0 +1,25 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#include "rpg/cutscene/item/cutsceneitem.h"
+#include "rpg/cutscene/cutscenesystem.h"
+#include "rpg/entity/entity.h"
+
+void cutsceneEmojiStart(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+) {
+  entity_t *entity = cutsceneSystemGetEntity(item->emoji.entityIndex);
+  uiEmojiAdd(entity->id, item->emoji.duration, item->emoji.emojiType);
+}
+
+bool_t cutsceneEmojiUpdate(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+) {
+  return true;
+}

src/dusk/rpg/cutscene/item/ui/cutsceneemoji.h

@@ -0,0 +1,43 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#pragma once
+#include "dusk.h"
+#include "ui/rpg/uiemoji.h"
+
+typedef struct cutsceneitem_s cutsceneitem_t;
+typedef union cutsceneitemdata_u cutsceneitemdata_t;
+
+typedef struct {
+  uint8_t entityIndex;
+  float_t duration;
+  uiemojitype_t emojiType;
+} cutsceneemoji_t;
+
+/**
+ * Starts an emoji step (shows an emoji above the entity for the given
+ * duration, then completes immediately).
+ *
+ * @param item The cutscene item.
+ * @param data Runtime data storage.
+ */
+void cutsceneEmojiStart(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+);
+
+/**
+ * Updates an emoji step (always completes immediately).
+ *
+ * @param item The cutscene item.
+ * @param data Runtime data storage.
+ * @returns true always.
+ */
+bool_t cutsceneEmojiUpdate(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+);

src/dusk/rpg/cutscene/item/ui/cutsceneshake.c

@@ -0,0 +1,23 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#include "rpg/cutscene/item/cutsceneitem.h"
+#include "rpg/rpgcamera.h"
+
+void cutsceneShakeStart(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+) {
+  rpgCameraShake(item->shake.amount, item->shake.duration);
+}
+
+bool_t cutsceneShakeUpdate(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+) {
+  return true;
+}

src/dusk/rpg/cutscene/item/ui/cutsceneshake.h

@@ -0,0 +1,41 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#pragma once
+#include "dusk.h"
+
+typedef struct cutsceneitem_s cutsceneitem_t;
+typedef union cutsceneitemdata_u cutsceneitemdata_t;
+
+typedef struct {
+  uint8_t amount;
+  float_t duration;
+} cutsceneshake_t;
+
+/**
+ * Starts a camera shake item (kicks off the shake on the RPG camera).
+ *
+ * @param item The cutscene item.
+ * @param data Runtime data storage.
+ */
+void cutsceneShakeStart(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+);
+
+/**
+ * Updates a camera shake item. The shake itself runs asynchronously on
+ * the RPG camera, so this always completes immediately.
+ *
+ * @param item The cutscene item.
+ * @param data Runtime data storage.
+ * @returns true always.
+ */
+bool_t cutsceneShakeUpdate(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+);

src/dusk/rpg/cutscene/item/ui/cutscenetext.c

@@ -6,7 +6,7 @@
  */
 
 #include "rpg/cutscene/item/cutsceneitem.h"
-#include "ui/rpg/uitextboxmain.h"
+#include "ui/rpg/textbox/uitextboxmain.h"
 
 void cutsceneTextStart(
   const cutsceneitem_t *item,

src/dusk/rpg/cutscene/item/ui/cutscenetextmini.c

@@ -0,0 +1,33 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#include "rpg/cutscene/item/cutsceneitem.h"
+#include "rpg/cutscene/cutscenesystem.h"
+#include "ui/rpg/textbox/uitextboxminilist.h"
+
+void cutsceneTextMiniStart(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+) {
+  uint8_t index = uiTextboxMiniListGetNext();
+  uiTextboxMiniShow(
+    &UI_TEXTBOX_MINI_LIST[index],
+    item->textMini.text,
+    item->textMini.position,
+    item->textMini.duration,
+    NULL,
+    NULL
+  );
+  CUTSCENE_SYSTEM.textMiniLastCreated = index;
+}
+
+bool_t cutsceneTextMiniUpdate(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+) {
+  return true;
+}

src/dusk/rpg/cutscene/item/ui/cutscenetextmini.h

@@ -0,0 +1,44 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#pragma once
+#include "dusk.h"
+
+typedef struct cutsceneitem_s cutsceneitem_t;
+typedef union cutsceneitemdata_u cutsceneitemdata_t;
+
+#define CUTSCENE_TEXT_MINI_MAX_CHARS 128
+
+typedef struct {
+  char_t text[CUTSCENE_TEXT_MINI_MAX_CHARS];
+  vec3 position;
+  float_t duration;
+} cutscenetextmini_t;
+
+/**
+ * Starts a mini text item (shows a mini textbox at the given world
+ * position for the given duration, then completes immediately).
+ *
+ * @param item The cutscene item.
+ * @param data Runtime data storage.
+ */
+void cutsceneTextMiniStart(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+);
+
+/**
+ * Updates a mini text item (always completes immediately).
+ *
+ * @param item The cutscene item.
+ * @param data Runtime data storage.
+ * @returns true always.
+ */
+bool_t cutsceneTextMiniUpdate(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+);

src/dusk/rpg/cutscene/item/ui/cutscenetextminihide.c

@@ -0,0 +1,25 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#include "rpg/cutscene/item/cutsceneitem.h"
+#include "rpg/cutscene/cutscenesystem.h"
+#include "ui/rpg/textbox/uitextboxminilist.h"
+
+void cutsceneTextMiniHideStart(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+) {
+  uint8_t index = cutsceneSystemGetTextMiniId(item->textMiniHide.index);
+  uiTextboxMiniClose(&UI_TEXTBOX_MINI_LIST[index]);
+}
+
+bool_t cutsceneTextMiniHideUpdate(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+) {
+  return true;
+}

src/dusk/rpg/cutscene/item/ui/cutscenetextminihide.h

@@ -0,0 +1,39 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#pragma once
+#include "dusk.h"
+
+typedef struct cutsceneitem_s cutsceneitem_t;
+typedef union cutsceneitemdata_u cutsceneitemdata_t;
+
+typedef struct {
+  uint8_t index;
+} cutscenetextminihide_t;
+
+/**
+ * Starts a mini text hide step (closes the mini textbox immediately).
+ *
+ * @param item The cutscene item.
+ * @param data Runtime data storage.
+ */
+void cutsceneTextMiniHideStart(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+);
+
+/**
+ * Updates a mini text hide step (always completes immediately).
+ *
+ * @param item The cutscene item.
+ * @param data Runtime data storage.
+ * @returns true always.
+ */
+bool_t cutsceneTextMiniHideUpdate(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+);

src/dusk/rpg/cutscene/scene/testcutscene.h

@@ -9,17 +9,6 @@
 #include "rpg/cutscene/cutscene.h"
 #include "rpg/cutscene/cutscenesystem.h"
 
-CUTSCENE(TEST_ONE, DEFAULT,
+CUTSCENE(TEST_ONE, 0, DEFAULT,
   CUTSCENE_TEXT("Test One."),
-);
-
-CUTSCENE(TEST_TWO, DEFAULT,
-  CUTSCENE_TEXT("Test Two."),
-  CUTSCENE_CONCURRENT(
-    CUTSCENE_ENTITY_WALK_TO(CUTSCENE_ENTITY_INTERACT, 4, 4, 0),
-    CUTSCENE_ENTITY_WALK_TO(CUTSCENE_ENTITY_INTERACTED, 8, 2, 0),
-  ),
-  CUTSCENE_ITEM_GIVE(ITEM_ID_POTATO, 3),
-  CUTSCENE_ENTITY_REMOVE(CUTSCENE_ENTITY_INTERACT),
-  CUTSCENE_TEXT("Done."),
 );

src/dusk/rpg/entity/CMakeLists.txt

@@ -14,4 +14,5 @@ target_sources(${DUSK_LIBRARY_TARGET_NAME}
 
 add_subdirectory(anim)
 add_subdirectory(interact)
-add_subdirectory(npc)
+add_subdirectory(npc)
+add_subdirectory(item)

src/dusk/rpg/entity/anim/entityanim.c

@@ -6,7 +6,7 @@
  */
 
 #include "rpg/entity/entity.h"
-#include "rpg/overworld/map.h"
+#include "rpg/overworld/chunk.h"
 #include "rpg/overworld/tile.h"
 #include "time/time.h"
 #include "entityanimwalk.h"
@@ -19,7 +19,7 @@ const entityanimcallback_t ENTITY_ANIM_CALLBACKS[ENTITY_ANIM_COUNT] = {
 };
 
 float_t entityAnimTileZOffset(const worldpos_t pos) {
-  return tileIsRamp(mapGetTile(pos)) ? 0.5f : 0.0f;
+  return tileShapeIsRamp(chunkGetTile(pos).shape) ? 0.5f : 0.0f;
 }
 
 void entityAnimUpdate(entity_t *entity) {
@@ -32,7 +32,7 @@ void entityAnimUpdate(entity_t *entity) {
       ) {
         entity->walkEndCooldown = ENTITY_ANIM_WALK_TURN_COOLDOWN;
       }
-      entity->animation = ENTITY_ANIM_IDLE;
+      entity->animation = ENTITY_ANIM_IDLE; 
       entity->animTime = 0;
     }
   }

src/dusk/rpg/entity/entity.c

@@ -8,11 +8,14 @@
 #include "entity.h"
 #include "assert/assert.h"
 #include "util/memory.h"
+#include "util/string.h"
 #include "time/time.h"
 #include "util/math.h"
-#include "rpg/overworld/map.h"
+#include "rpg/overworld/maparea.h"
 #include "rpg/overworld/chunk.h"
 #include "rpg/overworld/tile.h"
+#include "rpg/cutscene/cutscene.h"
+#include "yyjson.h"
 
 entity_t ENTITIES[ENTITY_COUNT];
 
@@ -27,6 +30,7 @@ void entityInit(entity_t *entity, const entitytype_t type) {
 
   memoryZero(entity, sizeof(entity_t));
   entity->id = (uint8_t)(entity - ENTITIES);
+  entity->globalId = ENTITY_GLOBAL_ID_NULL;
   entity->type = type;
   entity->chunkIndex = 0xFF;
 
@@ -60,6 +64,10 @@ bool_t entityCanRun(entity_t *entity) {
   return entity->animation == ENTITY_ANIM_IDLE;
 }
 
+bool_t entityCanUnload(entity_t *entity) {
+  return entity->globalId < ENTITY_GLOBAL_ID_START;
+}
+
 void entityTurn(entity_t *entity, const entitydir_t direction) {
   if(!entityCanTurn(entity)) return;
   entity->direction = direction;
@@ -82,45 +90,45 @@ void entityWalk(entity_t *entity, const entitydir_t direction) {
   }
 
   // Get tile under foot
-  tile_t tileCurrent = mapGetTile(entity->position);
-  tile_t tileNew = mapGetTile(newPos);
+  tile_t tileCurrent = chunkGetTile(entity->position);
+  tile_t tileNew = chunkGetTile(newPos);
   bool_t fall = false;
   bool_t raise = false;
 
   // Are we walking up a ramp?
   if(
-    tileIsRamp(tileCurrent) &&
+    tileShapeIsRamp(tileCurrent.shape) &&
     (
       // Can only walk UP the direction the ramp faces.
-      (direction+TILE_SHAPE_RAMP_NORTH) == tileCurrent ||
+      (direction+TILE_SHAPE_RAMP_NORTH) == tileCurrent.shape ||
       // If diagonal ramp, can go up one of two ways only. Inner ramps
       // share the same allowed directions as their outer counterparts.
       (
         (
           (
-            tileCurrent == TILE_SHAPE_RAMP_SOUTHEAST ||
-            tileCurrent == TILE_SHAPE_RAMP_SOUTHEAST_INNER
+            tileCurrent.shape == TILE_SHAPE_RAMP_SOUTHEAST ||
+            tileCurrent.shape == TILE_SHAPE_RAMP_SOUTHEAST_INNER
           ) &&
           (direction == ENTITY_DIR_SOUTH || direction == ENTITY_DIR_EAST)
         ) ||
         (
           (
-            tileCurrent == TILE_SHAPE_RAMP_SOUTHWEST ||
-            tileCurrent == TILE_SHAPE_RAMP_SOUTHWEST_INNER
+            tileCurrent.shape == TILE_SHAPE_RAMP_SOUTHWEST ||
+            tileCurrent.shape == TILE_SHAPE_RAMP_SOUTHWEST_INNER
           ) &&
           (direction == ENTITY_DIR_SOUTH || direction == ENTITY_DIR_WEST)
         ) ||
         (
           (
-            tileCurrent == TILE_SHAPE_RAMP_NORTHEAST ||
-            tileCurrent == TILE_SHAPE_RAMP_NORTHEAST_INNER
+            tileCurrent.shape == TILE_SHAPE_RAMP_NORTHEAST ||
+            tileCurrent.shape == TILE_SHAPE_RAMP_NORTHEAST_INNER
           ) &&
           (direction == ENTITY_DIR_NORTH || direction == ENTITY_DIR_EAST)
         ) ||
         (
           (
-            tileCurrent == TILE_SHAPE_RAMP_NORTHWEST ||
-            tileCurrent == TILE_SHAPE_RAMP_NORTHWEST_INNER
+            tileCurrent.shape == TILE_SHAPE_RAMP_NORTHWEST ||
+            tileCurrent.shape == TILE_SHAPE_RAMP_NORTHWEST_INNER
           ) &&
           (direction == ENTITY_DIR_NORTH || direction == ENTITY_DIR_WEST)
         )
@@ -129,55 +137,60 @@ void entityWalk(entity_t *entity, const entitydir_t direction) {
     )
   ) {
     tile_t tileNewSaved = tileNew;
-    tileNew = TILE_SHAPE_NULL;
+    tileNew = TILE_NULL;
     worldpos_t abovePos = newPos;
     abovePos.z += 1;
-    tile_t tileAbove = mapGetTile(abovePos);
+    tile_t tileAbove = chunkGetTile(abovePos);
 
-    if(tileAbove != TILE_SHAPE_NULL && tileIsWalkable(tileAbove)) {
+    if(
+      tileAbove.shape != TILE_SHAPE_NULL &&
+      tileShapeIsWalkable(tileAbove.shape)
+    ) {
       raise = true;
     } else {
       tileNew = tileNewSaved;
     }
-  } else if(tileNew == TILE_SHAPE_NULL && newPos.z > 0) {
+  } else if(tileNew.shape == TILE_SHAPE_NULL && newPos.z > 0) {
     // Falling down?
     worldpos_t belowPos = newPos;
     belowPos.z -= 1;
-    tile_t tileBelow = mapGetTile(belowPos);
+    tile_t tileBelow = chunkGetTile(belowPos);
     if(
-      tileBelow != TILE_SHAPE_NULL &&
-      tileIsRamp(tileBelow) &&
+      tileBelow.shape != TILE_SHAPE_NULL &&
+      tileShapeIsRamp(tileBelow.shape) &&
       (
         // This handles regular cardinal ramps
-        (entityDirGetOpposite(direction)+TILE_SHAPE_RAMP_NORTH) == tileBelow ||
+        (
+          entityDirGetOpposite(direction)+TILE_SHAPE_RAMP_NORTH
+        ) == tileBelow.shape ||
         // This handles diagonal ramps. Inner ramps share the same
         // allowed directions as their outer counterparts.
         (
           (
             (
-              tileBelow == TILE_SHAPE_RAMP_SOUTHEAST ||
-              tileBelow == TILE_SHAPE_RAMP_SOUTHEAST_INNER
+              tileBelow.shape == TILE_SHAPE_RAMP_SOUTHEAST ||
+              tileBelow.shape == TILE_SHAPE_RAMP_SOUTHEAST_INNER
             ) &&
             (direction == ENTITY_DIR_NORTH || direction == ENTITY_DIR_WEST)
           ) ||
           (
             (
-              tileBelow == TILE_SHAPE_RAMP_SOUTHWEST ||
-              tileBelow == TILE_SHAPE_RAMP_SOUTHWEST_INNER
+              tileBelow.shape == TILE_SHAPE_RAMP_SOUTHWEST ||
+              tileBelow.shape == TILE_SHAPE_RAMP_SOUTHWEST_INNER
             ) &&
             (direction == ENTITY_DIR_NORTH || direction == ENTITY_DIR_EAST)
           ) ||
           (
             (
-              tileBelow == TILE_SHAPE_RAMP_NORTHEAST ||
-              tileBelow == TILE_SHAPE_RAMP_NORTHEAST_INNER
+              tileBelow.shape == TILE_SHAPE_RAMP_NORTHEAST ||
+              tileBelow.shape == TILE_SHAPE_RAMP_NORTHEAST_INNER
             ) &&
             (direction == ENTITY_DIR_SOUTH || direction == ENTITY_DIR_WEST)
           ) ||
           (
             (
-              tileBelow == TILE_SHAPE_RAMP_NORTHWEST ||
-              tileBelow == TILE_SHAPE_RAMP_NORTHWEST_INNER
+              tileBelow.shape == TILE_SHAPE_RAMP_NORTHWEST ||
+              tileBelow.shape == TILE_SHAPE_RAMP_NORTHWEST_INNER
             ) &&
             (direction == ENTITY_DIR_SOUTH || direction == ENTITY_DIR_EAST)
           )
@@ -190,7 +203,7 @@ void entityWalk(entity_t *entity, const entitydir_t direction) {
   }
 
   // Can we walk here?
-  if(!raise && !fall && !tileIsWalkable(tileNew)) return;// Blocked
+  if(!raise && !fall && !tileShapeIsWalkable(tileNew.shape)) return;// Blocked
 
   // Raise/fall must be applied before checking for blocking entities,
   // otherwise the check compares against the wrong z-level.
@@ -213,6 +226,8 @@ void entityWalk(entity_t *entity, const entitydir_t direction) {
   entity->position = newPos;
   entity->animation = ENTITY_ANIM_WALK;
   entity->animTime = ENTITY_ANIM_WALK_DURATION;// TODO: Running vs walking
+  entityUpdateChunk(entity);
+  mapAreaCheckEntity(entity);
 }
 
 void entityRun(entity_t *entity, const entitydir_t direction) {
@@ -235,6 +250,17 @@ entity_t * entityGetAt(const worldpos_t position) {
   return NULL;
 }
 
+entity_t * entityGetByGlobalId(const entityglobalid_t globalId) {
+  entity_t *ent = ENTITIES;
+  do {
+    if(ent->type == ENTITY_TYPE_NULL) continue;
+    if(ent->globalId != globalId) continue;
+    return ent;
+  } while(++ent, ent < &ENTITIES[ENTITY_COUNT]);
+
+  return NULL;
+}
+
 uint8_t entityGetAvailable() {
   entity_t *ent = ENTITIES;
   do {
@@ -251,13 +277,14 @@ void entityPositionSet(entity_t *entity, const worldpos_t pos) {
   entity->animation = ENTITY_ANIM_IDLE;
   entity->animTime = 0;
   entity->walkEndCooldown = 0;
+  entityUpdateChunk(entity);
 }
 
 void entitySetChunk(entity_t *entity, const uint8_t chunkIndex) {
   assertNotNull(entity, "Entity pointer cannot be NULL");
 
   if(entity->chunkIndex != 0xFF) {
-    chunk_t *old = mapGetChunk(entity->chunkIndex);
+    chunk_t *old = chunkGet(entity->chunkIndex);
     if(old != NULL) {
       for(uint8_t i = 0; i < CHUNK_ENTITY_COUNT_MAX; i++) {
         if(old->entities[i] != entity->id) continue;
@@ -270,7 +297,7 @@ void entitySetChunk(entity_t *entity, const uint8_t chunkIndex) {
   entity->chunkIndex = chunkIndex;
 
   if(chunkIndex != 0xFF) {
-    chunk_t *next = mapGetChunk(chunkIndex);
+    chunk_t *next = chunkGet(chunkIndex);
     if(next != NULL) {
       for(uint8_t i = 0; i < CHUNK_ENTITY_COUNT_MAX; i++) {
         if(next->entities[i] != 0xFF) continue;
@@ -279,4 +306,166 @@ void entitySetChunk(entity_t *entity, const uint8_t chunkIndex) {
       }
     }
   }
+}
+
+void entityUpdateChunk(entity_t *entity) {
+  assertNotNull(entity, "Entity pointer cannot be NULL");
+
+  chunkpos_t cp;
+  worldPosToChunkPos(&entity->position, &cp);
+  chunkindex_t ci = chunkGetIndexAt(cp);
+  if(ci != -1) entitySetChunk(entity, (uint8_t)ci);
+}
+
+errorret_t entityCreateFromJson(yyjson_val *obj, entity_t **outEntity) {
+  assertNotNull(obj, "Entity JSON object cannot be NULL");
+  assertNotNull(outEntity, "Output entity pointer cannot be NULL");
+
+  yyjson_val *typeVal = yyjson_obj_get(obj, "type");
+  if(!typeVal || !yyjson_is_str(typeVal)) {
+    errorThrow("Entity JSON missing 'type' string");
+  }
+  const char_t *typeStr = yyjson_get_str(typeVal);
+
+  entitytype_t type;
+  if(stringEquals(typeStr, "player")) {
+    type = ENTITY_TYPE_PLAYER;
+  } else if(stringEquals(typeStr, "npc")) {
+    type = ENTITY_TYPE_NPC;
+  } else if(stringEquals(typeStr, "item")) {
+    type = ENTITY_TYPE_ITEM;
+  } else {
+    errorThrow("Entity JSON has unknown 'type': %s", typeStr);
+  }
+
+  yyjson_val *posVal = yyjson_obj_get(obj, "position");
+  if(!posVal || !yyjson_is_arr(posVal) || yyjson_arr_size(posVal) != 3) {
+    errorThrow("Entity JSON missing 'position' [x, y, z] array");
+  }
+  worldunit_t pos[3];
+  size_t posIdx, posLen;
+  yyjson_val *posElem;
+  yyjson_arr_foreach(posVal, posIdx, posLen, posElem) {
+    if(!yyjson_is_num(posElem)) {
+      errorThrow("Entity JSON 'position' elements must be numbers");
+    }
+    pos[posIdx] = (worldunit_t)yyjson_get_num(posElem);
+  }
+
+  entitydir_t direction = ENTITY_DIR_SOUTH;
+  yyjson_val *dirVal = yyjson_obj_get(obj, "direction");
+  if(dirVal && yyjson_is_str(dirVal)) {
+    const char_t *dirStr = yyjson_get_str(dirVal);
+    if(stringEquals(dirStr, "north")) {
+      direction = ENTITY_DIR_NORTH;
+    } else if(stringEquals(dirStr, "east")) {
+      direction = ENTITY_DIR_EAST;
+    } else if(stringEquals(dirStr, "south")) {
+      direction = ENTITY_DIR_SOUTH;
+    } else if(stringEquals(dirStr, "west")) {
+      direction = ENTITY_DIR_WEST;
+    } else {
+      errorThrow("Entity JSON has unknown 'direction': %s", dirStr);
+    }
+  }
+
+  // Item entities require a valid item reference, resolved up front so a
+  // bad reference fails before an entity slot is ever claimed.
+  itemid_t itemId = ITEM_ID_NULL;
+  uint8_t itemQuantity = 1;
+  if(type == ENTITY_TYPE_ITEM) {
+    yyjson_val *itemVal = yyjson_obj_get(obj, "item");
+    if(!itemVal || !yyjson_is_str(itemVal)) {
+      errorThrow("Entity JSON with type 'item' missing 'item' string");
+    }
+    const char_t *itemStr = yyjson_get_str(itemVal);
+    itemId = itemGetIdByName(itemStr);
+    if(itemId == ITEM_ID_NULL) {
+      errorThrow("Entity JSON references unknown item '%s'", itemStr);
+    }
+
+    yyjson_val *quantityVal = yyjson_obj_get(obj, "quantity");
+    if(quantityVal && yyjson_is_int(quantityVal)) {
+      itemQuantity = (uint8_t)yyjson_get_int(quantityVal);
+    }
+  }
+
+  // Only one player may exist at a time - it always holds the reserved
+  // ENTITY_GLOBAL_ID_PLAYER global ID, so that's how callers (e.g. the
+  // camera) find it regardless of how it was spawned.
+  if(
+    type == ENTITY_TYPE_PLAYER &&
+    entityGetByGlobalId(ENTITY_GLOBAL_ID_PLAYER) != NULL
+  ) {
+    errorThrow("A player entity has already been spawned");
+  }
+
+  // NPC path waypoints, resolved up front for the same reason as above.
+  worldpos_t path[NPC_PATH_COUNT_MAX];
+  uint8_t pathCount = 0;
+  if(type == ENTITY_TYPE_NPC) {
+    yyjson_val *pathVal = yyjson_obj_get(obj, "path");
+    if(pathVal) {
+      if(!yyjson_is_arr(pathVal)) {
+        errorThrow("Entity JSON 'path' must be an array");
+      }
+      size_t count = yyjson_arr_size(pathVal);
+      if(count == 0 || count > NPC_PATH_COUNT_MAX) {
+        errorThrow(
+          "Entity JSON 'path' must have 1-%d waypoints", NPC_PATH_COUNT_MAX
+        );
+      }
+
+      size_t pathIdx, pathLen;
+      yyjson_val *pathElem;
+      yyjson_arr_foreach(pathVal, pathIdx, pathLen, pathElem) {
+        if(!yyjson_is_arr(pathElem) || yyjson_arr_size(pathElem) != 3) {
+          errorThrow("Entity JSON 'path' entries must be [x, y, z] arrays");
+        }
+        worldunit_t comps[3];
+        size_t compIdx, compLen;
+        yyjson_val *compElem;
+        yyjson_arr_foreach(pathElem, compIdx, compLen, compElem) {
+          if(!yyjson_is_num(compElem)) {
+            errorThrow("Entity JSON 'path' elements must be numbers");
+          }
+          comps[compIdx] = (worldunit_t)yyjson_get_num(compElem);
+        }
+        path[pathIdx] = (worldpos_t){ comps[0], comps[1], comps[2] };
+      }
+      pathCount = (uint8_t)count;
+    }
+  }
+
+  // Interact cutscene, resolved up front for the same reason as above.
+  const cutscene_t *cutscene = NULL;
+  yyjson_val *cutsceneVal = yyjson_obj_get(obj, "cutscene");
+  if(cutsceneVal) {
+    if(!yyjson_is_str(cutsceneVal)) {
+      errorThrow("Entity JSON 'cutscene' must be a string");
+    }
+    errorChain(cutsceneGetByName(yyjson_get_str(cutsceneVal), &cutscene));
+  }
+
+  uint8_t index = entityGetAvailable();
+  if(index == 0xFF) errorThrow("No available entity slots");
+
+  entity_t *entity = &ENTITIES[index];
+  entityInit(entity, type);
+  entity->direction = direction;
+  entityPositionSet(entity, (worldpos_t){ pos[0], pos[1], pos[2] });
+  if(type == ENTITY_TYPE_ITEM) entityItemSet(entity, itemId, itemQuantity);
+  if(pathCount > 0) {
+    npcSetMoveType(entity, NPC_MOVE_TYPE_PATH);
+    for(uint8_t i = 0; i < pathCount; i++) {
+      npcPathAddNode(&entity->data.npc, path[i]);
+    }
+  }
+  if(cutscene != NULL) {
+    entity->interact.type = ENTITY_INTERACT_CUTSCENE;
+    entity->interact.data.cutscene = cutscene;
+  }
+
+  *outEntity = entity;
+  errorOk();
 }

src/dusk/rpg/entity/entity.h

@@ -13,9 +13,17 @@
 #include "npc/npc.h"
 
 typedef struct map_s map_t;
+typedef struct yyjson_val yyjson_val;
+
+typedef uint16_t entityglobalid_t;
+
+#define ENTITY_GLOBAL_ID_NULL 0
+#define ENTITY_GLOBAL_ID_START 1
+#define ENTITY_GLOBAL_ID_PLAYER 1
 
 typedef struct entity_s {
   uint8_t id;
+  entityglobalid_t globalId;
   entitytype_t type;
   entitytypedata_t data;
 
@@ -75,6 +83,16 @@ bool_t entityCanWalk(entity_t *entity);
  */
 bool_t entityCanRun(entity_t *entity);
 
+/**
+ * Returns true if the entity is allowed to be unloaded. By default this is
+ * true for entities whose global ID falls within the randomly assigned
+ * range below ENTITY_GLOBAL_ID_START.
+ *
+ * @param entity Pointer to the entity to check.
+ * @returns True if the entity can be unloaded.
+ */
+bool_t entityCanUnload(entity_t *entity);
+
 /**
  * Turn an entity to face a new direction.
  *
@@ -101,13 +119,21 @@ void entityRun(entity_t *entity, const entitydir_t direction);
 
 /**
  * Gets the entity at a specific world position.
- * 
+ *
  * @param map Pointer to the map to check.
  * @param pos The world position to check.
  * @return Pointer to the entity at the position, or NULL if none.
  */
 entity_t *entityGetAt(const worldpos_t pos);
 
+/**
+ * Gets the entity with the given global ID, if one is currently loaded.
+ *
+ * @param globalId The global ID to search for.
+ * @return Pointer to the matching entity, or NULL if none is loaded.
+ */
+entity_t *entityGetByGlobalId(const entityglobalid_t globalId);
+
 /**
  * Gets an available entity index.
  *
@@ -124,10 +150,57 @@ uint8_t entityGetAvailable();
  */
 void entitySetChunk(entity_t *entity, const uint8_t chunkIndex);
 
+/**
+ * Resolves the chunk that an entity's current position falls into and
+ * assigns the entity to it via entitySetChunk. Leaves the entity's chunk
+ * unchanged if its position doesn't fall within any loaded chunk.
+ *
+ * @param entity Pointer to the entity to update.
+ */
+void entityUpdateChunk(entity_t *entity);
+
 /**
  * Instantly moves an entity to a world position, resetting movement state.
  *
  * @param entity Pointer to the entity to move.
  * @param pos The world position to place the entity at.
  */
-void entityPositionSet(entity_t *entity, const worldpos_t pos);
+void entityPositionSet(entity_t *entity, const worldpos_t pos);
+
+/**
+ * Parses an entity descriptor from a yyjson object and spawns it as a new
+ * entity in an available slot. Expected shape:
+ *   { "type": "npc", "position": [x, y, z], "direction": "south" }
+ * "type" must be one of "player", "npc", "item". "direction" is optional
+ * (one of "north", "east", "south", "west") and defaults to
+ * ENTITY_DIR_SOUTH when absent.
+ *
+ * When "type" is "item", two extra fields apply:
+ *   { "type": "item", "position": [x, y, z], "item": "POTION",
+ *     "quantity": 1 }
+ * "item" (required) is the item's string ID, resolved via
+ * itemGetIdByName. "quantity" (optional) defaults to 1.
+ *
+ * When "type" is "player", the spawned entity is assigned the reserved
+ * ENTITY_GLOBAL_ID_PLAYER global ID (so entityGetByGlobalId can find it
+ * regardless of how it was spawned), and it is an error to spawn a
+ * second one while one is already loaded.
+ *
+ * When "type" is "npc", an optional "path" field sets it up with
+ * NPC_MOVE_TYPE_PATH movement:
+ *   { "type": "npc", "position": [x, y, z],
+ *     "path": [[4, 4, 0], [10, 10, 1]] }
+ * "path" must have 1-NPC_PATH_COUNT_MAX waypoints.
+ *
+ * Any entity type may set an optional "cutscene" field to wire up an
+ * interact component that starts the named cutscene (resolved via
+ * cutsceneGetByName) when interacted with:
+ *   { "type": "npc", "position": [x, y, z], "cutscene": "test_npc" }
+ *
+ * @param obj The yyjson object describing the entity.
+ * @param outEntity Output pointer, set to the newly spawned entity on
+ *   success.
+ * @return Any error that occurs (missing/invalid fields, unknown item,
+ *   duplicate player, unknown/malformed cutscene, no free slots).
+ */
+errorret_t entityCreateFromJson(yyjson_val *obj, entity_t **outEntity);

src/dusk/rpg/entity/entitypathstep.c

@@ -24,7 +24,9 @@ bool_t entityPathStep(
     "Entity pointer is out of bounds"
   );
 
-  if(worldPosIsEqual(entity->position, target)) return true;
+  if(worldPosIsEqual(entity->position, target) && entityCanWalk(entity)) {
+    return true;
+  }
   if(!entityCanWalk(entity)) return false;
 
   entitydir_t dir;

src/dusk/rpg/entity/entitytype.h

@@ -8,12 +8,14 @@
 #pragma once
 #include "rpg/entity/player.h"
 #include "npc/npc.h"
+#include "item/entityitem.h"
 
 typedef enum {
   ENTITY_TYPE_NULL,
-  
+
   ENTITY_TYPE_PLAYER,
   ENTITY_TYPE_NPC,
+  ENTITY_TYPE_ITEM,
 
   ENTITY_TYPE_COUNT
 } entitytype_enum_t;
@@ -23,6 +25,7 @@ typedef uint8_t entitytype_t;
 typedef union {
   player_t player;
   npc_t npc;
+  entityitem_t item;
 } entitytypedata_t;
 
 typedef struct {
@@ -50,5 +53,10 @@ static const entitycallback_t ENTITY_CALLBACKS[ENTITY_TYPE_COUNT] = {
   [ENTITY_TYPE_NPC] = {
     .init = npcInit,
     .movement = npcMovement,
+  },
+
+  [ENTITY_TYPE_ITEM] = {
+    .init = entityItemInit,
+    .movement = entityItemMovement,
   }
 };

src/dusk/rpg/entity/interact/entityinteract.c

@@ -8,7 +8,7 @@
 #include "rpg/entity/entity.h"
 #include "assert/assert.h"
 #include "rpg/cutscene/cutscenesystem.h"
-#include "ui/rpg/uitextboxmain.h"
+#include "ui/rpg/textbox/uitextboxmain.h"
 
 void entityInteractWith(entity_t *player, entity_t *target) {
   assertNotNull(player, "Player entity pointer cannot be NULL");
@@ -40,6 +40,14 @@ void entityInteractWith(entity_t *player, entity_t *target) {
       // entityTurn(player, player->direction); // Redundant (for now)
       break;
 
+    case ENTITY_INTERACT_CALLBACK:
+      assertNotNull(
+        target->interact.data.callback,
+        "Interact callback pointer cannot be NULL"
+      );
+      target->interact.data.callback(player, target);
+      break;
+
     case ENTITY_INTERACT_NULL:
       break;
 

src/dusk/rpg/entity/interact/entityinteract.h

@@ -7,9 +7,9 @@
 
 #pragma once
 #include "dusk.h"
-#include "rpg/cutscene/cutscene.h"
 
 typedef struct entity_s entity_t;
+typedef struct cutscene_s cutscene_t;
 
 /**
  * Describes the type of interaction an entity supports.

src/dusk/rpg/entity/item/CMakeLists.txt

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

src/dusk/rpg/entity/item/entityitem.c

@@ -0,0 +1,44 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#include "entityitem.h"
+#include "rpg/entity/entity.h"
+#include "assert/assert.h"
+#include "rpg/item/itemgive.h"
+#include "ui/rpg/textbox/uitextboxmain.h"
+
+void entityItemInit(entity_t *entity) {
+  assertNotNull(entity, "Entity pointer cannot be NULL");
+  entity->interact.type = ENTITY_INTERACT_CALLBACK;
+  entity->interact.data.callback = entityItemInteract;
+}
+
+void entityItemSet(
+  entity_t *entity,
+  const itemid_t item,
+  const uint8_t quantity
+) {
+  assertNotNull(entity, "Entity pointer cannot be NULL");
+  entity->data.item.item = item;
+  entity->data.item.quantity = quantity;
+}
+
+void entityItemInteract(entity_t *player, entity_t *target) {
+  assertNotNull(player, "Player entity pointer cannot be NULL");
+  assertNotNull(target, "Target entity pointer cannot be NULL");
+
+  itemGive(target->data.item.item, target->data.item.quantity);
+  target->data.item.collected = true;
+}
+
+void entityItemMovement(entity_t *entity) {
+  assertNotNull(entity, "Entity pointer cannot be NULL");
+  if(!entity->data.item.collected) return;
+  if(uiTextboxMainIsActive()) return;
+
+  entity->type = ENTITY_TYPE_NULL;
+}

src/dusk/rpg/entity/item/entityitem.h

@@ -0,0 +1,56 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#pragma once
+#include "rpg/item/item.h"
+
+typedef struct entity_s entity_t;
+
+typedef struct {
+  itemid_t item;
+  uint8_t quantity;
+  bool_t collected;
+} entityitem_t;
+
+/**
+ * Initializes an item entity. Wires up the interact component so that
+ * interacting with the entity gives its item and removes it.
+ *
+ * @param entity Pointer to the entity structure to initialize.
+ */
+void entityItemInit(entity_t *entity);
+
+/**
+ * Sets the item and quantity represented by an item entity.
+ *
+ * @param entity Pointer to the entity structure.
+ * @param item The item ID to give when picked up.
+ * @param quantity The quantity to give when picked up.
+ */
+void entityItemSet(
+  entity_t *entity,
+  const itemid_t item,
+  const uint8_t quantity
+);
+
+/**
+ * Interact callback for item entities. Gives the entity's item to the
+ * player and shows the pickup message. The entity itself is removed once
+ * the message has been dismissed, via entityItemMovement.
+ *
+ * @param player Pointer to the player entity.
+ * @param target Pointer to the item entity being picked up.
+ */
+void entityItemInteract(entity_t *player, entity_t *target);
+
+/**
+ * Update callback for item entities. Removes the entity once its pickup
+ * message has been dismissed. No-op if the item hasn't been collected.
+ *
+ * @param entity Pointer to the entity structure to update.
+ */
+void entityItemMovement(entity_t *entity);