@m2c2kit/cli 0.1.9 → 0.1.12

package/dist/.env

@@ -1 +1 @@
-CLI_VERSION=0.1.9
+CLI_VERSION=0.1.12

package/dist/cli.js

@@ -146,6 +146,10 @@ await yarg
             sourceFilePath: path.join(packageHomeFolderPath, "fonts", "roboto", "Roboto-Regular.ttf"),
             destinationFilePath: path.join(newFolderPath, "fonts", "roboto", "Roboto-Regular.ttf"),
         },
+        {
+            sourceFilePath: path.join(packageHomeFolderPath, "scripts", "post-install.mjs"),
+            destinationFilePath: path.join(newFolderPath, "post-install.mjs"),
+        },
     ];
     let errorCopyingFiles = false;
     copyFiles.forEach((c) => {

package/dist/scripts/post-install.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import fs from "fs";
+import { resolve, basename } from "path";
+
+const { dependencies } = JSON.parse(fs.readFileSync("./package.json"));
+
+/** If this m2c2kit app uses surveys, then copy the required css
+ * files from node_modules so they can be bundled */
+if (Object.keys(dependencies).includes("@m2c2kit/survey")) {
+  // does ./css folder exist? if not, create
+  if (!fs.existsSync("./css")) {
+    fs.mkdirSync("./css");
+  }
+
+  const cssDistDir = "./node_modules/@m2c2kit/survey/dist/css/";
+  const cssFiles = fs
+    .readdirSync(cssDistDir, {
+      withFileTypes: true,
+    })
+    .filter((dirent) => !dirent.isDirectory())
+    .map((dirent) => resolve(cssDistDir, dirent.name));
+
+  cssFiles.forEach((file) => {
+    const sourceContents = fs.readFileSync(file);
+    fs.writeFileSync(`./css/${basename(file)}`, sourceContents);
+  });
+}

package/dist/templates/index.html.handlebars

@@ -20,7 +20,7 @@
         height: 100vh;
         width: 100vw;
       ">
-    <canvas style="height: 100vh; width: 100vw"></canvas>
+    <canvas style="height: 100vh; width: 100vw" id="m2c2-canvas"></canvas>
       <!-- If you don't want the game to start immediately, remove session.start()
            from the code and call session.start() somehow else, such as with
            the button shown below or a programmatic call -->

package/dist/templates/package.json.handlebars

@@ -3,18 +3,19 @@
   "version": "1.0.0",
   "scripts": {
     "serve": "rollup -c --watch --configServe",
-    "build": "rollup -c --configProd"
+    "build": "rollup -c --configProd",
+    "postinstall": "node ./post-install.mjs"
   },
   "private": true,
   "dependencies": {
-    "@m2c2kit/core": "0.1.7",
-    "@m2c2kit/addons": "0.1.7"
+    "@m2c2kit/core": "0.1.10",
+    "@m2c2kit/addons": "0.1.10"
   },
   "devDependencies": {
-    "rollup": "2.63.0",
-    "@rollup/plugin-typescript": "8.3.0",
+    "rollup": "2.70.0",
+    "@rollup/plugin-typescript": "8.3.1",
     "@rollup/plugin-node-resolve": "13.1.3",
-    "@rollup/plugin-commonjs": "21.0.1",
+    "@rollup/plugin-commonjs": "21.0.2",
     "rollup-plugin-shim": "1.0.0",
     "rollup-plugin-copy": "3.4.0",
     "rollup-plugin-delete": "2.0.0",

package/dist/templates/rollup.config.js.handlebars

@@ -58,7 +58,11 @@ export default (commandLineArgs) => {
             {
               src: "img/*",
               dest: `${outputFolder}/img`,
-            },            
+            },
+            {
+              src: "css/*",
+              dest: `${outputFolder}/css`,
+            },
           ],
           copyOnce: false,
           hook: "writeBundle",

package/dist/templates/starter.ts.handlebars

@@ -1,29 +1,30 @@
 import {
-  WebColors,
-  Action,
   Game,
+  Action,
   Scene,
-  Sprite,
-  Point,
+  Shape,
   Label,
+  WebColors,
   LabelHorizontalAlignmentMode,
-  Shape,
-  Rect,
-  GameOptions,
   GameParameters,
+  GameOptions,
   TrialSchema,
   Session,
-  GameTrialEvent,
-  GameLifecycleEvent,
   SessionLifecycleEvent,
-  EventBase,
-  EventType
+  ActivityDataEvent,
+  ActivityLifecycleEvent,
+  Sprite,
+  Timer,
 } from "@m2c2kit/core";
 import { Button, Instructions } from "@m2c2kit/addons";
 
 class {{className}} extends Game {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   constructor() {
+    /**
+     * These are configurable game parameters and their defaults.
+     * At run time, they can be changed with the setParameters() method.
+     */    
     const defaultParameters: GameParameters = {
       ReadyTime: {
         value: 1000,
@@ -33,9 +34,16 @@ class {{className}} extends Game {
       TrialNum: { value: 3, description: "How many trials to run" },
     };
 
+    /**
+     * This describes all the data that will be generated by the assessment.
+     * At runtime, when a trial completes, the data will be returned to the
+     * session with a callback, along with this schema transformed into
+     * JSON Schema Draft-07 format.
+     */    
     const demoTrialSchema: TrialSchema = {
       colorChosen: { type: "string", description: "the color that was picked" },
       correct: { type: "boolean", description: "was the answer correct?" },
+      responseTime: { type: "number", description: "response time (ms) to choose shape" }
     };
 
     const options: GameOptions = {
@@ -44,12 +52,12 @@ class {{className}} extends Game {
       uri: "https://your-repo-or-webpage-here",
       shortDescription: "A brief couple sentence description.",
       longDescription: "An extended, many-sentence description.",
-      showFps: true,
+      showFps: false,
       trialSchema: demoTrialSchema,
       parameters: defaultParameters,
-      // set this color so we can see the boundaries of the game during development,
-      // but typically we would not set this
-      bodyBackgroundColor: WebColors.Wheat,
+      // You can set this color so we can see the boundaries of the game during development,
+      // but typically we would not set this, so it is commented out
+      // bodyBackgroundColor: WebColors.Wheat,
       // note: using 2:1 aspect ratio, because that is closer to modern phones
       width: 400,
       height: 800,
@@ -80,6 +88,9 @@ class {{className}} extends Game {
     };
 
     super(options);
+  }
+
+  init(): void {
     // just for convenience, alias the variable game to "this"
     // (even though eslint doesn't like it)
     // eslint-disable-next-line @typescript-eslint/no-this-alias
@@ -97,6 +108,7 @@ class {{className}} extends Game {
           textFontSize: 24,
           titleFontSize: 30,
           image: "smiley",
+          imageMarginBottom: 24
         },
         {
           title: "{{appName}} Demo",
@@ -125,19 +137,19 @@ class {{className}} extends Game {
     const getReadyMessage = new Label({
       text: "Get Ready",
       fontSize: 24,
-      position: new Point(200, 400),
+      position: { x: 200, y: 400 },
     });
     getReadyScene.addChild(getReadyMessage);
 
     // example of how to use an image. The image must be previously loaded
     const starSprite = new Sprite({
       imageName: "star",
-      position: new Point(200, 500),
+      position: { x: 200, y: 500 },
     });
     getReadyScene.addChild(starSprite);
 
-    // getReadyScene.setup() has a callback that is executed each time this scene is shown
-    getReadyScene.setup(() => {
+    // getReadyScene.onSetup() has a callback that is executed each time this scene is shown
+    getReadyScene.onSetup(() => {
       getReadyScene.run(
         Action.Sequence([
           // Get the wait duration from the default game parameters, defined above
@@ -151,32 +163,32 @@ class {{className}} extends Game {
       );
     });
 
-    // these entities before the setup() can be defined outside of a setup()
+    // these entities before the onSetup() can be defined outside of a onSetup()
     // because they exist through multiple trials
     // Their position and how they respond to interactions may differ across trials,
-    // and that logic will be written within a setup()
+    // and that logic will be written within a onSetup()
     const chooseRectangleScene = new Scene({
       backgroundColor: WebColors.LightGray,
     });
     game.addScene(chooseRectangleScene);
     const redRect = new Shape({
-      rect: new Rect({ width: 150, height: 100 }),
+      rect: { width: 150, height: 100 },
       fillColor: WebColors.Red,
     });
     chooseRectangleScene.addChild(redRect);
     const blueRect = new Shape({
-      rect: new Rect({ width: 150, height: 100 }),
+      rect: { width: 150, height: 100 },
       fillColor: WebColors.Blue,
     });
     chooseRectangleScene.addChild(blueRect);
     const correctMessage = new Label({
       text: "CORRECT!",
-      position: new Point(200, 500),
+      position: { x: 200, y: 500 },
     });
 
     const chooseMessage = new Label({
       text: "Choose the red rectangle",
-      position: new Point(200, 200),
+      position: { x: 200, y: 200 },
     });
     chooseRectangleScene.addChild(chooseMessage);
 
@@ -184,32 +196,34 @@ class {{className}} extends Game {
     chooseRectangleScene.addChild(correctMessage);
     const wrongMessage = new Label({
       text: "WRONG!",
-      position: new Point(200, 500),
+      position: {x: 200, y: 500 },
     });
 
     wrongMessage.hidden = true;
     chooseRectangleScene.addChild(wrongMessage);
 
-    // chooseRectangleScene.setup() is passed a callback that is executed each
-    // time this scene is shown. Within setup(), We will randomly decide on
+    // chooseRectangleScene.onSetup() is passed a callback that is executed each
+    // time this scene is shown. Within onSetup(), We will randomly decide on
     // what side the red rectangle is shown
-    chooseRectangleScene.setup(() => {
+    chooseRectangleScene.onSetup(() => {
+      let responseTime = NaN;
       let redOnLeft = true;
       if (Math.random() > 0.5) {
         redOnLeft = false;
       }
 
       if (redOnLeft) {
-        redRect.position = new Point(100, 300);
-        blueRect.position = new Point(300, 300);
+        redRect.position = { x: 100, y: 300 };
+        blueRect.position = { x: 300, y: 300 };
       } else {
-        redRect.position = new Point(300, 300);
-        blueRect.position = new Point(100, 300);
+        redRect.position = { x: 300, y: 300 };
+        blueRect.position = { x: 100, y: 300 };;
       }
 
       // helper function to record the user's choice and
       // decide if we are done
       function recordUserInput(choseRedRect: boolean) {
+        game.addTrialData("responseTime", responseTime);
         game.addTrialData("correct", choseRedRect);
         if (choseRedRect) {
           game.addTrialData("colorChosen", "red");
@@ -231,6 +245,7 @@ class {{className}} extends Game {
           Action.Sequence([
             Action.Custom({
               callback: () => {
+                responseTime = Timer.elapsed("rt");
                 // once a choice is made, don't allow additional taps
                 redRect.isUserInteractionEnabled = false;
                 blueRect.isUserInteractionEnabled = false;
@@ -264,6 +279,7 @@ class {{className}} extends Game {
           Action.Sequence([
             Action.Custom({
               callback: () => {
+                responseTime = Timer.elapsed("rt");        
                 redRect.isUserInteractionEnabled = false;
                 blueRect.isUserInteractionEnabled = false;
               },
@@ -287,25 +303,25 @@ class {{className}} extends Game {
       });
     });
 
+    chooseRectangleScene.onAppear(() => {
+      Timer.removeAll();
+      Timer.start("rt");
+    });
+
     const endScene = new Scene();
     game.addScene(endScene);
     const doneLabel = new Label({
-      text: `This will be reassigned in the setup() callback. If you see this, something went wrong!`,
-      position: new Point(200, 300),
+      text: `This will be reassigned in the onSetup() callback. If you see this, something went wrong!`,
+      position: { x: 200, y: 300},
     });
     endScene.addChild(doneLabel);
 
     const startOverButton = new Button({
       text: "Start over",
-      position: new Point(200, 600),
+      position: { x: 200, y: 600 },
     });
     startOverButton.isUserInteractionEnabled = true;
     startOverButton.onTapDown(() => {
-      // in the setup() for the end scene, we animate the smiley sprite with
-      // a move action. if the user taps the start over button before the
-      // animation is completed, we should remove it by calling
-      // removeAllActions()
-      smileySprite.removeAllActions();
       game.initData();
       game.presentScene(getReadyScene);
     });
@@ -313,7 +329,7 @@ class {{className}} extends Game {
 
     const exitButton = new Button({
       text: "Exit",
-      position: new Point(200, 675),
+      position: { x: 200, y: 675 },
     });
     exitButton.isUserInteractionEnabled = true;
     exitButton.onTapDown(() => {
@@ -325,69 +341,14 @@ class {{className}} extends Game {
     });
     endScene.addChild(exitButton);
 
-    const smileySprite = new Sprite({ imageName: "smiley" });
-    endScene.addChild(smileySprite);
-
-    endScene.setup(() => {
+    endScene.onSetup(() => {
       doneLabel.text = `You did ${game.trialIndex} trials. You're done!`;
-
-      // example of how to position a sprite and create an action to move it
-      smileySprite.position = new Point(200, 500);
-      smileySprite.run(
-        Action.Move({ point: new Point(200, 100), duration: 3000 })
-      );
     });
 
     game.entryScene = "instructions-01";
   }
 }
 
-// ===========================================================================
-
-//#region to support m2c2kit in Android WebView
-/** When running within an Android WebView, the below defines how the session
- * can communicate events back to the Android app. Note: names of this Android
- * namespace and its functions must match the corresponding Android code
- * in addJavascriptInterface() and @JavascriptInterface */
-// eslint-disable-next-line @typescript-eslint/no-namespace
-declare namespace Android {
-  function onGameTrialComplete(gameTrialEventAsString: string): void;
-  function onGameLifecycleChange(gameLifecycleEventAsString: string): void;
-  function onSessionLifecycleChange(
-    sessionLifecycleEventAsString: string
-  ): void;
-  /** if the Android native app will control the session execution and be
-   * able to set custom game paraemters (which is probably what you want),
-   * be sure that sessionManualStart() in the native code returns true */
-  function sessionManualStart(): boolean;
-}
-
-function contextIsAndroidWebView(): boolean {
-  return typeof Android !== "undefined";
-}
-
-function sendEventToAndroid(event: EventBase) {
-  switch (event.eventType) {
-    case EventType.sessionLifecycle: {
-      Android.onSessionLifecycleChange(JSON.stringify(event));
-      break;
-    }
-    case EventType.gameTrial: {
-      Android.onGameTrialComplete(JSON.stringify(event));
-      break;
-    }
-    case EventType.gameLifecycle: {
-      Android.onGameLifecycleChange(JSON.stringify(event));
-      break;
-    }
-    default:
-      throw new Error(
-        `attempt to send unknown event ${event.eventType} to Android`
-      );
-  }
-}
-//#endregion
-
 const game1 = new {{className}}();
 // default was 3 trials; this is how we can specify a different value
 game1.setParameters({ TrialNum: 2 });
@@ -395,68 +356,71 @@ game1.setParameters({ TrialNum: 2 });
 const session = new Session({
   activities: [game1],
   sessionCallbacks: {
-    // onSessionLifecycleChange() will be called on events such
-    // as when the session initialization is complete. Once initialized,
-    // the session will automatically start, unless we're running
-    // in an Android WebView and a manual start is desired.
-    onSessionLifecycleChange: (event: SessionLifecycleEvent) => {
-      if (event.initialized) {
-        //#region to support m2c2kit in Android WebView
-        if (contextIsAndroidWebView()) {
-          sendEventToAndroid(event);
-        }
-        if (contextIsAndroidWebView() && Android.sessionManualStart()) {
-          return;
-        }
-        //#endregion
+    /**
+     * onSessionLifecycleChange() will be called on events such
+     * as when the session initialization is complete or when it
+     * ends.
+     *
+     * Once initialized, the session will automatically start,
+     * unless we're running in an Android WebView AND a manual start
+     * is desired.
+     */
+    onSessionLifecycleChange: (ev: SessionLifecycleEvent) => {
+      if (ev.initialized) {
         session.start();
       }
-      if (event.ended) {
+      if (ev.ended) {
         console.log("session ended");
-        //#region to support m2c2kit in Android WebView
-        if (contextIsAndroidWebView()) {
-          sendEventToAndroid(event);
-        }
-        //#endregion
       }
     },
   },
-  gameCallbacks: {
-    // onGameTrialComplete() is where you insert code to post data to an API
-    // or interop with a native function in the host app, if applicable    
-    onGameTrialComplete: (event: GameTrialEvent) => {
-      console.log(`********** trial (index ${event.trialIndex}) complete`);
-      console.log("data: " + JSON.stringify(event.gameData));
-      console.log("trial schema: " + JSON.stringify(event.trialSchema));
-      console.log("game parameters: " + JSON.stringify(event.gameParameters));
-
-      //#region to support m2c2kit in Android WebView
-      if (contextIsAndroidWebView()) {
-        sendEventToAndroid(event);
-      }
-      //#endregion
+  activityCallbacks: {
+    /**
+     * onActivityDataCreate() is where you insert code to post data to an API
+     * or interop with a native function in the host app.
+     *
+     * newData is the data that was just generated by the completed trial
+     * data is all the data, cumulative of all trials, that have been generated.
+     *
+     * We separate out newData from data in case you want to alter the execution
+     * based on the most recent trial, e.g., maybe you want to stop after
+     * a certain user behavior or performance threshold in the just completed
+     * trial.
+     */
+    onActivityDataCreate: (ev: ActivityDataEvent) => {
+      console.log(`********** trial complete`);
+      console.log("newData: " + JSON.stringify(ev.newData));
+      console.log("newData schema: " + JSON.stringify(ev.newDataSchema));
+      console.log("data: " + JSON.stringify(ev.data));
+      console.log("data schema: " + JSON.stringify(ev.dataSchema));
+      console.log(
+        "activity parameters: " + JSON.stringify(ev.activityConfiguration)
+      );
     },
-    onGameLifecycleChange: (event: GameLifecycleEvent) => {
-      if (event.ended) {
-        console.log(`ended game ${event.gameName}`);
+    /**
+     * onActivityLifecycleChange() notifies us when an activity, such
+     * as an assessment or a survey, has completed. Usually, however,
+     * we want to know when all the activities are done, so we'll
+     * look for the session ending via onSessionLifecycleChange
+     */
+    onActivityLifecycleChange: (ev: ActivityLifecycleEvent) => {
+      if (ev.ended) {
+        console.log(`ended activity ${ev.name}`);
         if (session.nextActivity) {
           session.advanceToNextActivity();
         } else {
           session.end();
         }
-        //#region to support m2c2kit in Android WebView
-        if (contextIsAndroidWebView()) {
-          sendEventToAndroid(event);
-        }
-        //#endregion
       }
     },
   },
 });
 
-/** make session also available on window in case we want to control
+/**
+ * Make session also available on window in case we want to control
  * the session through another means, such as other javascript or
- * browser code, or the Android WebView loadUrl() method */
+ * browser code, or the Android WebView loadUrl() method
+ * */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 (window as unknown as any).session = session;
 session.init();

package/dist/templates/tsconfig.json.handlebars

@@ -19,6 +19,7 @@
     "build",
     "dist",
     "**/{{appName}}.bundle.js",
-    "rollup.config.js"
+    "rollup.config.js",
+    "post-install.mjs"
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m2c2kit/cli",
-  "version": "0.1.9",
+  "version": "0.1.12",
   "description": "m2c2kit command line interface",
   "module": "dist/cli.js",
   "files": [
@@ -17,28 +17,28 @@
     "build": "npm run clean && npm run compile && npm run copy-files && npm run write-dotenv",
     "compile": "tsc",
     "clean": "rimraf dist/ && rimraf build/",
-    "copy-files": "copyfiles -f build/src/cli.js dist && copyfiles templates/* fonts/**/* dist/",
+    "copy-files": "copyfiles -f build/src/cli.js dist && copyfiles scripts/* templates/* fonts/**/* dist/",
     "write-dotenv": "node write-dotenv.js"
   },
   "author": "",
   "license": "MIT",
   "dependencies": {
     "axios": "0.24.0",
-    "chalk": "5.0.0",
+    "chalk": "5.0.1",
     "conf": "10.1.1",
     "form-data": "4.0.0",
     "handlebars": "4.7.7",
-    "ora": "6.0.1",
+    "ora": "6.1.0",
     "prompts": "2.4.2",
     "yargs": "17.3.1"
   },
   "devDependencies": {
-    "@types/node": "17.0.8",
+    "@types/node": "17.0.21",
     "@types/prompts": "2.0.14",
-    "@types/yargs": "17.0.8",
+    "@types/yargs": "17.0.9",
     "copyfiles": "2.4.1",
     "rimraf": "3.0.2",
     "tslib": "2.3.1",
-    "typescript": "4.5.4"
+    "typescript": "4.6.2"
   }
 }