@m2c2kit/cli 0.1.8 → 0.1.11

package/dist/.env

@@ -1 +1 @@
-CLI_VERSION=0.1.8
+CLI_VERSION=0.1.11

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.6",
-    "@m2c2kit/addons": "0.1.6"
+    "@m2c2kit/core": "0.1.9",
+    "@m2c2kit/addons": "0.1.9"
   },
   "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,26 +1,30 @@
 import {
-  WebColors,
-  Action,
   Game,
+  Action,
   Scene,
-  Sprite,
-  Point,
+  Shape,
   Label,
+  WebColors,
   LabelHorizontalAlignmentMode,
-  Shape,
-  Rect,
-  GameOptions,
   GameParameters,
+  GameOptions,
   TrialSchema,
   Session,
-  GameTrialEvent,
-  GameLifecycleEvent,
+  SessionLifecycleEvent,
+  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(specifiedParameters?: 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,
@@ -30,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 = {
@@ -41,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,
@@ -76,7 +87,10 @@ class {{className}} extends Game {
       ],
     };
 
-    super(options, specifiedParameters);
+    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
@@ -94,6 +108,7 @@ class {{className}} extends Game {
           textFontSize: 24,
           titleFontSize: 30,
           image: "smiley",
+          imageMarginBottom: 24
         },
         {
           title: "{{appName}} Demo",
@@ -122,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
@@ -148,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);
 
@@ -181,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");
@@ -228,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;
@@ -261,6 +279,7 @@ class {{className}} extends Game {
           Action.Sequence([
             Action.Custom({
               callback: () => {
+                responseTime = Timer.elapsed("rt");        
                 redRect.isUserInteractionEnabled = false;
                 blueRect.isUserInteractionEnabled = false;
               },
@@ -284,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);
     });
@@ -310,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(() => {
@@ -322,78 +341,86 @@ 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";
   }
 }
 
-// ============================================================================
-
-// When running within an Android webview, the below defines how the session
-// can communicate events to the Android app. Note: the 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;
-}
-
+const game1 = new {{className}}();
 // default was 3 trials; this is how we can specify a different value
-const game1 = new {{className}}({ TrialNum: 2 });
+game1.setParameters({ TrialNum: 2 });
 
 const session = new Session({
   activities: [game1],
-  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: (e: GameTrialEvent) => {
-      console.log(`********** trial ${e.trialIndex} complete`);
-      console.log("data: " + JSON.stringify(e.gameData));
-      console.log("trial schema: " + JSON.stringify(e.trialSchema));
-      console.log("game parameters: " + JSON.stringify(e.gameParameters));
-
-      // callback to native Android app, if running in that context
-      if (typeof Android !== "undefined") {
-        Android.onGameTrialComplete(JSON.stringify(e));
+  sessionCallbacks: {
+    /**
+     * 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 (ev.ended) {
+        console.log("session ended");
       }
     },
-    // onGameLifecycleChange() is called when the game lifecycles changes
-    onGameLifecycleChange: (e: GameLifecycleEvent) => {
-      if (e.ended) {
-        console.log(`user requested exit in game ${e.gameName}`);
-        // this session has only one activity, but this is how it would go to
-        // the next activity
+  },
+  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)
+      );
+    },
+    /**
+     * 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();
-        }
-
-        // callback to native Android app, if running in that context
-        if (typeof Android !== "undefined") {
-          Android.onGameLifecycleChange(JSON.stringify(e));
+        } else {
+          session.end();
         }
       }
     },
   },
 });
 
-// make session also available on window in case we want to control
-// the session through another means
+/**
+ * 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
+ * */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 (window as unknown as any).session = session;
-
-session.init().then(() => {
-  session.start();
-});
+session.init();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m2c2kit/cli",
-  "version": "0.1.8",
+  "version": "0.1.11",
   "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"
   }
 }