Merge pull request #69 from cayb0rg/feature/inventory-system

Feature/inventory system

.github/workflows/release-build.yml

@@ -4,21 +4,21 @@ on:
     # Sequence of patterns matched against refs/tags
     tags:
      - 'v[0-9]+.[0-9]+.[0-9]+'
-     - 'v[0-9]+.[0-9]+.[0-9]+-rc[0-9]+'
-     - 'v[0-9]+.[0-9]+.[0-9]+-alpha[0-9]+'
+     - 'v[0-9]+.[0-9]+.[0-9]+-rc.[0-9]+'
+     - 'v[0-9]+.[0-9]+.[0-9]+-alpha.[0-9]+'
 jobs:
   deploy:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node-version: [12.x]
+        node-version: [18.13.0]
 
     steps:
     - name: Checkout code
-      uses: actions/checkout@v2
+      uses: actions/checkout@v4
 
     - name: Test and build with node ${{ matrix.node-version }}
-      uses: actions/setup-node@v1
+      uses: actions/setup-node@v3
       with:
         node-version: ${{ matrix.node-version }}
 
@@ -31,5 +31,5 @@ jobs:
         repo_token: ${{ secrets.GITHUB_TOKEN }}
         file: build/_output/*
         tag: ${{ github.ref }}
-        overwrite: false
-        file_glob: true
+        overwrite: true
+        file_glob: true

.github/workflows/test.yml

@@ -1,22 +1,19 @@
-
 name: Run Tests
 on: [push, pull_request]
 jobs:
   test:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node-version: [12.3.1, 12.x]
-
+        node-version: [18.13.0]
     steps:
     - name: Checkout code
-      uses: actions/checkout@v2
-
+      uses: actions/checkout@v4
     - name: Run tests with Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v1
+      uses: actions/setup-node@v3
       with:
         node-version: ${{ matrix.node-version }}
     - run: npm install -g yarn
     - run: yarn install
     # - run: yarn test-ci # no tests....... yet
-    - run: yarn build
+    - run: yarn build

.gitignore

@@ -3,4 +3,4 @@ build
 .sass-cache
 node_modules
 com.adobe.flexbuilder.project.prefs
-build.local.properties
+build.local.properties

load_icons.sh

@@ -0,0 +1,36 @@
+#! /bin/bash
+# Creates JS file containing an array of icon data (icon name and url)
+# Used to bypass writing out 100 objects in the initIcons function in creator-assets/controllers.coffee
+# ------------------------------------------------
+
+# Outputs list of file names into lsoutput.log
+ls -a ./src/assets/icons > lsoutput.log
+
+last_line=$(wc -l < lsoutput.log)
+current_line_number=0
+output="./src/assets/icons.js"
+
+FMT='{name:"%s",url:"%s"},'
+FMT_LAST_LINE='{name:"%s",url:"%s"}'
+
+printf 'icons = [' > $output
+
+# Reads lsoutput.log and inserts each filename into JSON file
+while read -r CURRENT_LINE
+    current_line_number=$(($current_line_number + 1))
+    do
+        if [[ $current_line_number -ne $last_line ]]; then
+            if [[ $CURRENT_LINE == *".png" ]]; then
+                printf "$FMT" "$CURRENT_LINE" "assets/icons/$CURRENT_LINE" >> $output
+            fi
+        else
+            printf "$FMT_LAST_LINE" "$CURRENT_LINE" "assets/icons/$CURRENT_LINE" >> $output
+            break
+        fi
+done < lsoutput.log
+
+printf "]" >> $output
+
+rm lsoutput.log
+
+# Go to src/assets/icons.js and copy paste it into the initIcons function in creator-assets/controllers.coffee

package.json

@@ -3,15 +3,15 @@
   "materia": {
     "cleanName": "adventure"
   },
-  "version": "2.3.2",
+  "version": "2.3.1",
   "dependencies": {
-    "materia-widget-development-kit": "2.5.2",
+    "materia-widget-development-kit": "^3.0.1",
     "micromarkdown": "^0.3.0"
   },
   "scripts": {
-    "start": "webpack-dev-server",
-    "build": "webpack -p",
-    "build-dev": "webpack",
+    "start": "mwdk-start",
+    "build": "mwdk-build-prod",
+    "build-dev": "mwdk-build-dev",
     "test": "echo 'tests not implemented",
     "test-ci": "echo 'tests not implemented'"
   },

sample_score_data.json

@@ -0,0 +1 @@
+[{"overview":{"complete":"1","score":80,"table":[{"message":"Points Lost","value":-20},{"message":"Final Score","value":80}],"referrer_url":"","created_at":1698767344,"auth":""},"details":[{"title":"Where did you end up?","header":[],"table":[{"data":["Nice job! Despite some missteps, you\u0027ve helped the child recover and successfully diagnosed and treated his dehydration. The mother thanks you earnestly as they leave."],"data_style":["node_text"],"score":80,"type":"SCORE_FINAL_FROM_CLIENT","style":"single_column","tag":"p","symbol":"%","graphic":"none","display_score":false}]},{"title":"Responses:","header":["Question Score","The Question","Your Response"],"table":[]}]}]

src/_guides/creator.md

@@ -11,6 +11,7 @@ Each point on the tree, known as a *destination* or *node*, represents a screen
 1. Title of the widget
 2. A blank destination
 3. Zoom controls
+4. Inventory items
 
 ## Details ##
 
@@ -62,17 +63,19 @@ Each destination type is identified by an icon. An example tree is shown below:
 
 The Short Answer screen is very similar to the Multiple Choice screen, with the exception of how it handles answers. Users enter a response based on the question text or image.
 
-![adventure creator shortanswer](assets/create_widget_adventure_screen_sa.png "adventure creator shortanswer")
+![adventure creator shortanswer](assets/create_widget_adventure_screen_sa_updated.png "adventure creator shortanswer")
 
 1. Question text field
 2. Add an image to accompany the question
 3. Add a new word or phrase to match
 4. Set of words or phrases that can be matched for this answer
-5. Optional feedback to accompany this set of answers
-6. The destination this answer set will point to
-7. Delete this answer set
-8. Add an additional answer set
-9. The catch-all answer set if a user's response does not match any provided answers
+5. Option to make matches case sensitive (e.g. "match" will be treated differently than "MATCH")
+6. Option to make matches special character sensitive (e.g. "$5" will be treated differently than "5")
+7. Optional feedback to accompany this set of answers
+8. The destination this answer set will point to
+9. Delete this answer set
+10. Add an additional answer set
+11. The catch-all answer set if a user's response does not match any provided answers
 
 <aside>
 	The widget will attempt to match the user's response to all possible answers provided across all answer sets. If no match is made, the <em>Unmatched Answers</em> choice is selected.
@@ -170,6 +173,125 @@ For any destination type besides Hotspot, selecting the **Add Media** button cha
 
 If you choose to upload an image, the image uploader will be displayed, where you can upload images from your computer, or select an image you've previously uploaded to Materia. Once you've selected an image or video, you can use the **Swap with Question** button below the media to switch the arrangement of the image and question text. Narrative and End Point destinations allow you to choose between vertical as well as horizontal arrangements. Select **Change Media** to choose a different image or video.
 
+## Inventory System ##
+
+Optionally, you can choose to use the inventory system. The inventory system allows you to give the player items or remove items from the player's inventory for each destination they visit.
+
+Additionally, you can require the player to have certain items in their inventory to be able to select an answer option in Multiple Choice, Short Answer, or Hotspot.
+
+### Creating Inventory Items ###
+
+To use the inventory system, you must first create the items. Click **Add Inventory Items**.
+
+![adventure add inventory button](assets/create_widget_adventure_add_inventory_items.png "adventure add inventory button")
+
+This will open the Item Editor where you can begin creating items.
+
+![adventure item editor](assets/create_widget_adventure_item_editor.png "adventure item editor")
+
+1. Enter Item Name
+2. Add Item
+3. Save and Close the Item Editor.
+4. Edit Item
+5. Delete Item (This will also remove the item from all destinations it has been added to. Adding items to destinations will be explained in the next section.)
+
+Clicking **Edit** will open the options for that specific item.
+
+![adventure item editor options](assets/create_widget_adventure_item_editor_options.png "adventure item editor options")
+
+1. Edit the item name
+2. (Optional) Add Item Description
+3. (Optional) Open the Icon Selector
+4. Save Item
+5. (Advanced) Make this a silent item. The player will not see this item in their inventory nor see it listed as a required item for an answer. An instance where this could be useful is in a choices-matter scenario. You could have an answer appear (or not appear) if the player has made a certain choice in the past.
+6. Delete Item
+
+#### Icon Selector ####
+To add icons to an item, click **Select Icon** to open the Icon Selector.
+
+![adventure item icon selector](assets/create_widget_adventure_icon_selector.png "adventure item icon selector")
+
+1. Click an icon to select it. Click it again to remove it.
+2. To upload your own icon, select **Upload Icon** inside the icon selector. This will display the image uploader. PNG, JPG, and SVG files are all accepted. Uploaded icons will show up at the bottom of the icon selector.
+
+Remove *custom uploaded icons* by selecting the icon in the icon selector and clicking **Remove Selected Icon**.
+
+![adventure item icon remove](assets/create_widget_adventure_icon_remove.png "adventure item icon remove")
+
+### Adding Items to Destinations ###
+
+Once you have created the inventory items, an option to add items to destinations will appear in any destination besides End Point.
+
+Selecting the **Add Items** button will display the item editor for individual nodes. Inside the editor, you can choose to add items to a player's inventory or remove items from a player's inventory.
+
+![adventure item add](assets/create_widget_adventure_add_items.png "adventure item add")
+
+1. Select an item from the dropdown
+2. Give the item to the player
+3. Take the item from the player. Note, however, that you can only remove an item from a player's inventory if they already have the item (i.e. you gave the player that item in a previous destination).
+4. Adjust the quantity of the item being given or taken. Only positive values greater than 0 are accepted.
+5. Remove the item
+6. Show Advanced Options.
+
+#### Advanced Options for Giving Items
+
+![adventure item advanced options](assets/create_widget_adventure_item_advanced_options_give.png "adventure item advanced options")
+
+Selecting "Give On First Visit Only" will give the player the item only once upon their initial visit to a destination; if the player returns to this destination, they will not receive the item again.
+
+#### Advanced Options for Taking Items
+
+![adventure item advanced options](assets/create_widget_adventure_item_advanced_options_take.png "adventure item advanced options")
+
+1. Take the item only upon the player's initial visit to the destination.
+2. Take all of this type of item from the player.
+
+### Adding Required Items to Answers ###
+
+Once you have created items, an option to add required items to Multiple Choice Answers, Short Answer Match Sets, or Hotspots will appear in the respective destination types, as indicated by the lock icon (1). An additional setting appears in multiple choice and hotspot answers that allows you to hide the answer if the player does not have the required item(s), indicated by the "eye" icon (2).
+
+#### Multiple Choice ####
+
+![adventure required item mc](assets/create_widget_adventure_mc_required_items.png "adventure required item mc")
+#### Hotspot ####
+
+![adventure required item hotspot](assets/create_widget_adventure_hotspot_required_items.png "adventure required item hotspot")
+
+#### Short Answer ####
+
+![adventure required item sa](assets/create_widget_adventure_sa_required_items.png "adventure required item sa")
+
+### Required Item Editor ###
+
+Although the image below was taken inside the Hotspot, the Required Item Editor appears and functions the same for each destination node type.
+
+![adventure required item editor](assets/create_widget_adventure_required_item_editor.png "adventure required item editor")
+
+1. Select an item from the dropdown
+2. Make the item required for this answer to be selected
+3. Change the amount required
+4. Remove the item from required items
+5. Show advanced options (see below)
+
+#### Advanced Options
+
+![adventure required item editor advanced options](assets/create_widget_adventure_required_item_editor_advanced.png "adventure required item editor advanced options")
+
+The advanced options allow you to set the required item amount to be within a specific range.
+
+1. Set the minimum number the player can have of this item to select this answer.
+2. Set the maximum number the player can have of this item to select this answer.
+3. (Default) Set the maximum to have no cap.
+
+### Example Tree Using Inventory System ###
+
+![adventure tree with items](assets/create_widget_adventure_tree_with_items.png "adventure tree with items")
+
+1. Destinations that give or take items will display them in a circle surrounding the node.
+2. Items being taken by the destination will have a red circle around them. Items being given will have a green circle around them.
+3. The lock icon indicates that the answer choice requires items in order for the player to select it. Hover over the lock to see which items are required.
+4. The total number of items created will be displayed by the **Edit Inventory Items** button in parantheses.
+
 ## Action History ##
 
 The Action History feature serves two purposes: first, it allows for immediate **undo** and **redo** options when required. Second, it allows you to traverse through previous actions and reset your work to a previous state. This way, you can easily recover from an unintended situation without having to re-create destinations or reload the widget and lose your work.

src/_guides/player.md

@@ -21,6 +21,18 @@ The hotspot screen is the one significant exception to the Adventure widget's la
 2. Hotspot image
 3. Example hotspot
 
+### Inventory
+Some widgets may give you items as you progress. You can view your items by clicking the backpack in the top right of the screen.
+
+![adventure player inventory button](assets/play_widget_adventure_inventory_button.png "adventure player inventory button")
+
+Your inventory will show what items you have, the quantity of those items, and their descriptions.
+
+Sometimes, multiple choice answers, hotspots, or even short answer responses require you to have certain items. Keep playing, and you might just end up finding these items!
+
+![adventure player required items example](assets/play_widget_adventure_required_items.png "adventure player required items example")
+
+
 ### Your Choices Determine Your Score ###
 
 In Choose Your Own Adventure, the score you receive is based on the final screen you encounter. Your responses to various questions determine the route you take; some widgets may be more linear than others. Additionally, you may or may not encounter screens of every type (Multiple Choice, Short Answer, Hotspot, and Narrative).

src/_score/score_module.php

@@ -80,7 +80,7 @@ protected function details_for_question_answered($log)
 		return [
 			'data' => [
 				$this->get_ss_question($log, $q),
-				$this->get_ss_answer($log, $q),
+				$this->get_ss_answer($log, $q)
 			],
 			'data_style'    => ['question', 'response', 'answer'],
 			'score'         => $score,
@@ -145,4 +145,4 @@ protected function get_score_details()
 			]
 		];
 	}
-}
+}