feat: sprite onclick arguments supports arguments (#41)

* First draft of sprite run with arguments

Instead of running onClick as a label name, allow arguments to also be passed into it. This allows for more sprite functionality flexibility.
In my case, an intercept function that allows me to play a noise when something is clicked, then jump to a supplied label.

I haven't tested it because uuuuh i dont know how.

* Split functionality into helper function

* feat: sprite onclick arguments improved and added docs for it

---------

Co-authored-by: Slashscreen <[email protected]>

CHANGELOG.md

@@ -1,5 +1,21 @@
 # Narrat changelog
 
+## [2.10.7] Passing arguments to sprite `onClick`
+
+Arguments can now be passed to the `onClick` property of a sprite, by passing a string with the label and space-separated arguments.
+
+It it also possible to make the `onClick` property be an object containing `label` (string), `method` (jump or run) and `args` (array of arguments) values for more advanced use cases.
+
+Example:
+
+```narrat
+test_sprites_click:
+  set data.sprite (create_sprite img/characters/cat_idle.webp 200 200)
+  set data.sprite.onClick "some_label someArgument"
+```
+
+Clicking on the sprite will jump to `some_label` and pass as first argument the value `someArgument`
+
 ## [2.10.6] - New `get_skill_check` and `skill_check_result` functions
 
 Those two new functions make it possible to access the data of a skill check.

packages/narrat/examples/games/default/scripts/default.nar

@@ -41,7 +41,7 @@ card_finder card name_to_match:
 
 test_sprites_click:
   set data.sprite (create_sprite img/characters/cat_idle.webp 200 200)
-  set data.sprite.onClick some_label
+  set data.sprite.onClick "some_label someArgument"
   set data.sprite2 (create_sprite img/characters/cat_idle.webp 50 100 $data.sprite)
   set data.text (create_object 50 100 $data.sprite2)
   set data.text.anchor.x 0.5
@@ -55,8 +55,8 @@ test_sprites_click:
   set data.sprite.y 100
 
 
-some_label:
-  talk player idle "Clicked on sprite"
+some_label arg:
+  talk player idle "Clicked on sprite %{$arg}"
   jump quest_demo
 
 test_load_data:

packages/narrat/package.json

@@ -1,6 +1,6 @@
 {
   "name": "narrat",
-  "version": "2.10.6",
+  "version": "2.10.7",
   "description": "narrat narrative engine",
   "main": "dist/narrat.umd.js",
   "module": "dist/narrat.es.js",

packages/narrat/src/stores/screen-objects-store.ts

@@ -10,6 +10,12 @@ import { useVM } from './vm-store';
 
 export type ScreenObjectType = 'screenObject' | 'sprite';
 
+export interface ObjectOnClick {
+  label: string;
+  method?: 'jump' | 'run';
+  args?: any[];
+}
+
 export interface ScreenObjectState {
   _entityType: ScreenObjectType;
   id: string;
@@ -27,7 +33,7 @@ export interface ScreenObjectState {
   scale: number;
   layer: number;
   cssClass?: string;
-  onClick?: string;
+  onClick?: ObjectOnClick | string;
   text?: string;
   clickMethod?: 'jump' | 'run';
   children: ScreenObjectState[];
@@ -78,6 +84,22 @@ export function isSprite(entity: any): entity is SpriteState {
   );
 }
 
+// Helper function that parses arguments given to a screenObject's onClick parameter,
+export function parseArgumentsFromOnClick(args: string) {
+  if (args.includes(' ')) {
+    // If it contains spaces, meaning multiple args
+    const splitArgs = args.split(' ');
+    return {
+      label: splitArgs[0],
+      args: splitArgs.slice(1),
+    };
+  } else {
+    return {
+      label: args,
+    };
+  }
+}
+
 export interface CreateSpriteOptions extends CreateObjectOptions {
   image: string;
 }
@@ -174,10 +196,25 @@ export const useScreenObjects = defineStore('screenObjects', {
       if (thing.onClick) {
         console.log('click', Date.now());
         audioEvent('onSpriteClicked');
-        if (thing.clickMethod === 'run') {
-          useVM().runThenGoBackToPreviousDialog(thing.onClick, true);
-        } else if (thing.clickMethod === 'jump' || !thing.clickMethod) {
-          useVM().jumpToLabel(thing.onClick);
+        let clickArgs: ObjectOnClick;
+        if (typeof thing.onClick === 'string') {
+          const parsedOnClick = parseArgumentsFromOnClick(thing.onClick);
+          clickArgs = {
+            label: parsedOnClick.label,
+            args: parsedOnClick.args,
+          };
+        } else {
+          clickArgs = thing.onClick;
+        }
+        clickArgs.method = clickArgs.method ?? thing.clickMethod ?? 'jump';
+        clickArgs.args = clickArgs.args ?? [];
+        if (clickArgs.method === 'run') {
+          useVM().runThenGoBackToPreviousDialog(
+            clickArgs.label,
+            ...clickArgs.args,
+          );
+        } else if (clickArgs.method === 'jump') {
+          useVM().jumpToLabel(clickArgs.label, ...clickArgs.args);
         } else {
           error(`Unknown sprite click method ${thing.clickMethod}`);
         }