feat: custom scenes working + new plugin hook (#290)

docs/.vitepress/config-en.ts

@@ -186,6 +186,7 @@ function sidebarPlugins(): DefaultTheme.SidebarItem[] {
       link: '/plugins/godot/godot-plugin',
     },
     { text: 'Plugin API', link: '/plugins/plugins' },
+    { text: 'Plugin hooks', link: '/plugins/plugin-hooks' },
   ];
 }
 

docs/plugins/plugin-hooks.md

@@ -0,0 +1,20 @@
+---
+title: Narrat Plugin Hooks
+description: The Narrat plugin API has hooks called by the engine at various stages of loading which can let you run custom code at those points.
+---
+
+## Plugin hooks
+
+Plugins can define hook functions that the engine will call at various stages of loading. These hooks can be used to run custom code at those points.
+
+### Available hooks
+
+- `onPageLoaded`: Earliest hook called as soon as the page starts
+- `onNarratSetup`: Called when the narrat app is created but before anything is mounted
+- `onAppMounted`: Called when the main narrat app has been mounted to the DOM
+- `onAssetsLoaded`: Called as soon as asset loading is over
+- `onGameSetup`: Called at the very end of the game loading process, before the engine properly starts
+- `onStartScreenMounted`: Called when the start screen has been mounted to the DOM
+- `onGameStart`: Called when a game starts via pressing new game or continue
+- `onGameMounted`: Called when the in-game scene has been mounted to the DOM (game has started playing)
+- `onGameUnmounted`: Called when the in-game scene has been unmounted from the DOM (game has stopped playing)

packages/narrat/src/components/StartMenu.vue

@@ -76,6 +76,7 @@ import {
   startNewGame,
   loadAndStartGame,
 } from '@/application/application-utils';
+import { vm } from '@/vm/vm';
 
 const inputListener = ref<InputListener | null>(
   useInputs().registerInputListener('start-menu', {}),
@@ -237,6 +238,7 @@ onMounted(() => {
   if (audioConfig().options.defaultMusic) {
     musicId.value = standalonePlayMusic(audioConfig().options.defaultMusic!);
   }
+  vm.callHook('onStartScreenMounted');
 });
 
 function setupButtons() {

packages/narrat/src/components/game-splash/game-splash.vue

@@ -40,7 +40,7 @@ const gameLoaded = computed(() => main.loading.loaded);
 const gameTitle = computed(() => getCommonConfig().gameTitle || 'Narrat Game');
 
 function goToStartMenu() {
-  useScenes().changeScene('start-menu');
+  useScenes().goToStartMenuScene();
 }
 onMounted(() => {
   inputListener.value = useInputs().registerInputListener('game-splash', {

packages/narrat/src/components/scenes/chapter-title.vue

@@ -13,6 +13,7 @@
 import { onMounted, onUnmounted, ref } from 'vue';
 import { useScenes } from '@/stores/scenes-store';
 import { useVM } from '@/stores/vm-store';
+import { BuiltInScene } from '@/scenes/default-scenes';
 
 const props = defineProps<{
   options: {
@@ -26,7 +27,7 @@ const props = defineProps<{
 const timeout = ref<any>(null);
 function finishedTimeout() {
   timeout.value = null;
-  useScenes().changeScene('playing');
+  useScenes().changeScene(BuiltInScene.Playing);
   useVM().jumpToLabel(props.options.next_label);
 }
 onMounted(() => {

packages/narrat/src/config/common-config.ts

@@ -135,6 +135,13 @@ export type ScriptsConfig = Static<typeof ScriptsConfigSchema>;
 
 export const defaultScriptsConfig = [];
 
+export const ScenesConfigSchema = Type.Object({
+  startMenuScene: Type.Optional(Type.String()),
+  gameScene: Type.Optional(Type.String()),
+});
+
+export type ScenesConfig = Static<typeof ScenesConfigSchema>;
+
 export const CommonConfigInputSchema = Type.Object({
   baseAssetsPath: Type.Optional(Type.String()),
   baseDataPath: Type.Optional(Type.String()),
@@ -158,7 +165,9 @@ export const CommonConfigInputSchema = Type.Object({
   debugging: Type.Optional(DebuggingConfigSchema),
   saves: Type.Optional(SavesConfigSchema),
   hotkeys: HotkeysConfigSchema,
+  scenes: Type.Optional(ScenesConfigSchema),
 });
+
 export type CommonConfigInput = Static<typeof CommonConfigInputSchema>;
 
 export interface CommonConfig {
@@ -184,6 +193,7 @@ export interface CommonConfig {
   debugging: DebuggingConfig;
   saves: SavesConfig;
   hotkeys: HotkeysConfig;
+  scenes: ScenesConfig;
 }
 
 export const defaultCommonConfig: CommonConfig = {
@@ -228,4 +238,5 @@ export const defaultCommonConfig: CommonConfig = {
     slots: 10,
   },
   hotkeys: {},
+  scenes: {},
 };

packages/narrat/src/exports/exports.ts

@@ -9,3 +9,4 @@ export * from '@/exports/components';
 export * from '@/exports/utils';
 export * from '@/exports/optionals';
 export * from '@/exports/plugins-list';
+export * from '@/exports/scenes';

packages/narrat/src/exports/scenes.ts

@@ -0,0 +1,2 @@
+export type { SceneConfig } from '@/scenes/scene-types';
+export { BuiltInScene } from '@/scenes/default-scenes';

packages/narrat/src/exports/stores.ts

@@ -16,4 +16,3 @@ export { useTooltips } from '@/stores/tooltip-store';
 export { useVM } from '@/stores/vm-store';
 export { useAchievements } from '@/stores/achievements-store';
 export { useScenes } from '@/stores/scenes-store';
-export type { SceneConfig } from '@/scenes/scene-types';

packages/narrat/src/plugins/NarratPlugin.ts

@@ -7,7 +7,8 @@ export class NarratPlugin<T = any> implements NarratPluginObject<T> {
   onAppMounted() {}
   onAssetsLoaded() {}
   onGameSetup() {}
+  onStartScreenMounted() {}
   onGameStart() {}
   onGameMounted() {}
-  onGameDismounted() {}
+  onGameUnmounted() {}
 }

packages/narrat/src/scenes/default-scenes.ts

@@ -6,29 +6,37 @@ import ChapterTitle from '@/components/scenes/chapter-title.vue';
 import { shallowRef } from 'vue';
 import { SceneConfig, SceneKey } from './scene-types';
 
+export enum BuiltInScene {
+  EngineSplash = 'engine-splash',
+  GameSplash = 'game-splash',
+  StartMenu = 'start-menu',
+  Playing = 'playing',
+  ChapterTitle = 'chapter-title',
+}
+
 export const defaultScenes = {
-  'engine-splash': {
-    id: 'engine-splash',
+  [BuiltInScene.EngineSplash]: {
+    id: BuiltInScene.EngineSplash,
     component: shallowRef(EngineSplash),
     props: {},
   },
-  'game-splash': {
-    id: 'game-splash',
+  [BuiltInScene.GameSplash]: {
+    id: BuiltInScene.GameSplash,
     component: shallowRef(GameSplash),
     props: {},
   },
-  'start-menu': {
-    id: 'start-menu',
+  [BuiltInScene.StartMenu]: {
+    id: BuiltInScene.StartMenu,
     component: shallowRef(StartMenu),
     props: {},
   },
-  playing: {
-    id: 'playing',
+  [BuiltInScene.Playing]: {
+    id: BuiltInScene.Playing,
     component: shallowRef(InGame),
     props: {},
   },
-  'chapter-title': {
-    id: 'chapter-title',
+  [BuiltInScene.ChapterTitle]: {
+    id: BuiltInScene.ChapterTitle,
     component: shallowRef(ChapterTitle),
     props: {},
   },

packages/narrat/src/stores/main-store.ts

@@ -139,7 +139,7 @@ export const useMain = defineStore('main', {
     prepareToPlay() {
       this.ready = true;
       this.startPlaying();
-      useScenes().changeScene('playing');
+      useScenes().goToGameScene();
     },
     setSaveSlot(slot: string) {
       this.saveSlot = slot;
@@ -167,7 +167,7 @@ export const useMain = defineStore('main', {
     },
     menuReturn() {
       // this.reset();
-      useScenes().changeScene('start-menu');
+      useScenes().goToStartMenuScene();
     },
     createError(text: string) {
       this.errors.push({

packages/narrat/src/stores/scenes-store.ts

@@ -1,5 +1,7 @@
 import { defineStore, acceptHMRUpdate } from 'pinia';
 import { SceneConfig, SceneKey } from '@/scenes/scene-types';
+import { getCommonConfig } from '@/config';
+import { BuiltInScene } from '@/scenes/default-scenes';
 
 export interface ScenesStoreState {
   scenes: Record<string, SceneConfig>;
@@ -16,15 +18,15 @@ export const useScenes = defineStore('scenes-store', {
   state: () =>
     ({
       scenes: {},
-      activeScene: 'engine-splash',
+      activeScene: BuiltInScene.EngineSplash,
       currentOptions: {},
     }) as ScenesStoreState,
   getters: {
     isPlaying(state) {
       return (
-        state.activeScene !== 'engine-splash' &&
-        state.activeScene !== 'game-splash' &&
-        state.activeScene !== 'start-menu'
+        state.activeScene !== BuiltInScene.EngineSplash &&
+        state.activeScene !== BuiltInScene.GameSplash &&
+        state.activeScene !== BuiltInScene.StartMenu
       );
     },
   },
@@ -37,7 +39,10 @@ export const useScenes = defineStore('scenes-store', {
     loadSaveData(saveData: ScenesStoreSave) {
       // this.activeScene = saveData.activeScene;
     },
-    changeScene(newScene: SceneKey, options?: Record<string, any>) {
+    changeScene(
+      newScene: string | BuiltInScene,
+      options?: Record<string, any>,
+    ) {
       const currentScene = this.activeScene;
       if (currentScene && currentScene !== newScene) {
         const currentSceneConfig = this.scenes[currentScene];
@@ -63,6 +68,20 @@ export const useScenes = defineStore('scenes-store', {
         this.scenes[sceneId].onFinished!();
       }
     },
+    goToStartMenuScene() {
+      let destination = BuiltInScene.StartMenu as string;
+      if (getCommonConfig().scenes.startMenuScene) {
+        destination = getCommonConfig().scenes.startMenuScene!;
+      }
+      this.changeScene(destination);
+    },
+    goToGameScene() {
+      let destination = BuiltInScene.Playing as string;
+      if (getCommonConfig().scenes.gameScene) {
+        destination = getCommonConfig().scenes.gameScene!;
+      }
+      this.changeScene(destination);
+    },
     addNewScene(sceneConfig: SceneConfig) {
       this.scenes[sceneConfig.id] = sceneConfig;
     },