Choose Your Own Adventure Player

plugins/chooseYourAdventurePlayer/README.md

@@ -0,0 +1,156 @@
+# Choose Your Own Adventure Player
+A plugin to adapt Choose Your Own Adventure Games to the Stash VideoJS player.
+
+## Setup
+The plugin provides various settings, but only the `Access tokem`, `Game tag`, `Resource path`, and `Scene directory path` settings are required for it to work. Note that this repo does not provide relevant JS and CSS files to run this plugin. To acquire these files, reach out to `_cj13` in the discord channel and provide your GitHub username, and you will be given access to the [BackerScripts](https://github.com/cj12312021/BackerScripts) repo.
+
+### Access token (Required)
+This plugin exists as an additional perk for our backers. So, an access token is required to identify users with access. If you are a backer of the project, feel free to reach out to me on our Discord channel with your GitHub account name in order to obtain the necessary access. Once your Github account has the permissions required, you will need to generate a classic personal access token with `repo` scope selected (See: [Creating a personal access token (classic)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic)). The generated access token is what you will provide here.
+
+### Game tag (Required)
+This is the name of the tag created to indicate that the selected game clip is the starting video for the game. (I would recommend setting your default filters up to hide other related videos that are not the starting video)
+
+### Resource path (Required)
+This is the path where the non-video game resources would live. For example, the path to the `Sample` directory would be the `Resource path`, which contains one game with the id `1234`. Each game within this directory is expected to have a choices directory with all the necessary JSON files as well as an `images` directory with all the relevant images for the game. You can configure assets directly in this plugin if you want. I would just recommend against it to prevent your game files from being deleted if you ever uninstalled this plugin from the Stash plugin page. I would recommend setting up a custom-served folder for your Stash; see: [Custom served folders](https://docs.stashapp.cc/in-app-manual/configuration/#custom-served-folders). Also, see the provided `Sample` directory for examples of what the relevant files should contain.
+
+### Scene directory path (Required)
+This is the path within your Stash library directories where your game scenes are stored. For example, the path to the `Sample` directory would be the `Scene directory path`, which contains one game with the id `1234`. In your case, the videos do not have to live under a videos directory within the `1234` directory.
+
+## Choice Files
+This section covers things to know when creating the choice JSON files.
+
+### Start Choice
+Every game should contain a `0.json` file, which is the starting file for these games. See the various properties of these files in the snippet below:
+
+```
+{
+  /* The id here should correspond with the name of the file */
+  "id": "0",
+  "type": null, // In most cases this can be null expect for when dealing with an end choice. This is explained later.
+  /* This is the name/title used for each choice. This name would be displayed when a dicision is required from the user. 
+     This name is not as important for the start choice */
+  "title": "Game Start",
+  /* This property is not required, but when provided it would include details about the game the user is about to play. 
+     This property would only exist in the 0.json file */
+  "map": { 
+    "title": "Demo",
+    "description": "Your are viewing a demo of the Choose Your Adventure Player"
+  },
+  /* This property is not required, but when provided it would provide an overview of the different branches of the game. 
+     This also serves as a portal user can take to navigate directly to specific branches */
+  "mapItem": [
+    {
+      "choice_id": "TBD", // id of the choice this overview is attempting to highlight
+      "title": "TBD",
+      "picture": null // name of relevant photo. Not required, however if provided it would ideally be an image relevant to the branch it overs
+    }
+  ],
+  /* This property can be specified in any choice. When provide it allows the user to skip dialog scenes and get striaght into the action. 
+     The provided value should be the id of the choice the user would be directed to. */
+  "skipto": "2",
+  /* Each json file should contain atleast one choice here (unless the json file is the final branch). When one choice is provided 
+     the game will navigae directly to the provided choice. When more than one choice is provided the user will be presented an 
+     option to make their own choice at the end of the scene. */
+  "choices": [
+    {
+      "description": "Good Choice", // text shown to user describing the choice
+      "id": "1a", // id of the next choice to load
+      "type": "",
+      "photo": null // name of relevant photo to further describe choice. WHen no photo is provided a default photo will be used.
+    },
+    {
+      "description": "Bad Choice",
+      "id": "1b",
+      "type": "",
+      "photo": null
+    }
+  ],
+  "resource": { // this should contain the name of the video that will be played as a part of this choice
+    "resolved_content": "Scene0.mp4"
+  }
+}
+```
+
+### Multi Scene Choices
+Multiple scenes can be provided within a choice. To do this, you would use the `fragments` property. This property will effectively replace the `resource` property, which can only contain one scene. Each fragment can include an action which is intended to be a shorter clip related to the fragment that the user can click as many times as they would like to repeat the action. For more info on how these can be used, see the example file below:
+
+```
+{
+  "id": "2",
+  "type": null,
+  "title": "Action choice",
+  "fragments": [
+    {
+      "id": "frag-a",
+      "photo": {
+        "id": "frag-a_photo",
+        "content": "frag-a.jpg"
+      },
+      "video": {
+        "id": "frag-a_video",
+        "resolved_content": "Scene2A.mp4"
+      },
+      "actions": [
+        {
+          "id": "frag-a-action-a",
+          "photo": {
+            "id": "frag-a-action-a_photo",
+            "content": "frag-a-action-a.jpg"
+          },
+          "video": {
+            "id": "frag-a-action-a_video",
+            "resolved_content": "Scene2A-1.mp4"
+          },
+          "title": "TBD"
+        },
+        {
+          "id": "frag-a-action-b",
+          "photo": {
+            "id": "frag-a-action-b_photo",
+            "content": "frag-a-action-b.jpg"
+          },
+          "video": {
+            "id": "frag-a-action-b_video",
+            "resolved_content": "Scene2A-1.mp4"
+          },
+          "title": "TBD"
+        }
+      ],
+      "title": "TBD"
+    },
+    {
+      "id": "frag-b",
+      "photo": {
+        "id": "frag-b_photo",
+        "content": "frag-b.jpg"
+      },
+      "video": {
+        "id": "frag-b_video",
+        "resolved_content": "Scene2B.mp4"
+      },
+      "actions": null,
+      "title": "TBA",
+      "subtitles": "Scene3-08"
+    }
+  ],
+  "skipto": null,
+  "choices": [
+    {
+      "description": null,
+      "id": "2-e",
+      "type": "end",
+      "photo": "TBD"
+    }
+  ],
+  "resource": {
+    "id": "empty",
+    "resolved_content": null
+  }
+}
+
+```
+
+### End Choice
+Similar to the start choice, each scene will contain an end choice. The choice will conclude the game. The choices are will either be of type `exit`, or `end`. 
+The `exit` type is effectively a fail choice, letting the user know they have failed the game. When a user encounters this, they will be given an option to go back and choose a different choice or simply restart the game.
+The `end` type is the success choice, letting the user know they have concluded the game as "intended". Once a user hits this screen, they can decide to replay the game from the start or exit it.

plugins/chooseYourAdventurePlayer/Sample/1234/choices/0.json

@@ -0,0 +1,34 @@
+{
+  "id": "0",
+  "type": null,
+  "title": "Game Start",
+  "map": {
+    "title": "Demo",
+    "description": "Your are viewing a demo of the Choose Your Adventure Player"
+  },
+  "mapItem": [
+    {
+      "choice_id": "TBD",
+      "title": "TBD",
+      "picture": "TBD.png"
+    }
+  ],
+  "skipto": "2",
+  "choices": [
+    {
+      "description": "Good Choice",
+      "id": "1a",
+      "type": "",
+      "photo": "TBD"
+    },
+    {
+      "description": "Bad Choice",
+      "id": "1b",
+      "type": "",
+      "photo": "TBD"
+    }
+  ],
+  "resource": {
+    "resolved_content": "Scene0.mp4"
+  }
+}

plugins/chooseYourAdventurePlayer/Sample/1234/choices/1a.json

@@ -0,0 +1,17 @@
+{
+  "id": "1a",
+  "type": null,
+  "title": "Good Choice",
+  "skipto": "2",
+  "choices": [
+    {
+      "description": null,
+      "id": "2",
+      "type": null,
+      "photo": "TBD"
+    }
+  ],
+  "resource": {
+    "resolved_content": "Scene1a.mp4"
+  }
+}

plugins/chooseYourAdventurePlayer/Sample/1234/choices/1b-e.json

@@ -0,0 +1,10 @@
+{
+  "id": "1b-e",
+  "type": "exit",
+  "title": "Bad Choice",
+  "skipto": null,
+  "choices": null,
+  "resource": {
+    "resolved_content": null
+  }
+}

plugins/chooseYourAdventurePlayer/Sample/1234/choices/1b.json

@@ -0,0 +1,17 @@
+{
+  "id": "1b",
+  "type": null,
+  "title": "Bad Choice",
+  "skipto": null,
+  "choices": [
+    {
+      "description": null,
+      "id": "1b-e",
+      "type": "exit",
+      "photo": "TBD"
+    }
+  ],
+  "resource": {
+    "resolved_content": "Scene1b.mp4"
+  }
+}

plugins/chooseYourAdventurePlayer/Sample/1234/choices/2-e.json

@@ -0,0 +1,10 @@
+{
+  "id": "2-e",
+  "type": "end",
+  "title": "",
+  "skipto": null,
+  "choices": null,
+  "resource": {
+    "resolved_content": null
+  }
+}

plugins/chooseYourAdventurePlayer/Sample/1234/choices/2.json

@@ -0,0 +1,72 @@
+{
+  "id": "2",
+  "type": null,
+  "title": "Action choice",
+  "fragments": [
+    {
+      "id": "frag-a",
+      "photo": {
+        "id": "frag-a_photo",
+        "content": "frag-a.jpg"
+      },
+      "video": {
+        "id": "frag-a_video",
+        "resolved_content": "Scene2A.mp4"
+      },
+      "actions": [
+        {
+          "id": "frag-a-action-a",
+          "photo": {
+            "id": "frag-a-action-a_photo",
+            "content": "frag-a-action-a.jpg"
+          },
+          "video": {
+            "id": "frag-a-action-a_video",
+            "resolved_content": "Scene2A-1.mp4"
+          },
+          "title": "TBD"
+        },
+        {
+          "id": "frag-a-action-b",
+          "photo": {
+            "id": "frag-a-action-b_photo",
+            "content": "frag-a-action-b.jpg"
+          },
+          "video": {
+            "id": "frag-a-action-b_video",
+            "resolved_content": "Scene2A-1.mp4"
+          },
+          "title": "TBD"
+        }
+      ],
+      "title": "TBD"
+    },
+    {
+      "id": "frag-b",
+      "photo": {
+        "id": "frag-b_photo",
+        "content": "frag-b.jpg"
+      },
+      "video": {
+        "id": "frag-b_video",
+        "resolved_content": "Scene2B.mp4"
+      },
+      "actions": null,
+      "title": "TBA",
+      "subtitles": "Scene3-08"
+    }
+  ],
+  "skipto": null,
+  "choices": [
+    {
+      "description": null,
+      "id": "2-e",
+      "type": "end",
+      "photo": "TBD"
+    }
+  ],
+  "resource": {
+    "id": "empty",
+    "resolved_content": null
+  }
+}

plugins/chooseYourAdventurePlayer/chooseYourAdventurePlayer.yml

@@ -0,0 +1,45 @@
+name: Choose Your Own Adventure Player
+description: Plugin to adapt Choose Your Own Adventure Games to the VideoJS player.
+version: 1.0.1
+# requires: CommunityScriptsUILibrary
+settings:
+  accessToken:
+    displayName: Access Token
+    description: Your personal Github access token needed to read private scripts
+    type: STRING
+  gameTag:
+    displayName: Game tag
+    description: Name of the tag indicating a scene is the starting point of game. Player will initialize once scene with this tag is loaded. Only use this tag on the starting scene.
+    type: STRING
+  enableGameSave:
+    displayName: Enable game save
+    description: When enabled you will be giving the opportunity to resume your games from where you last left off which all your choices in tack.
+    type: BOOLEAN
+  resourcePath:
+    displayName: Resource path
+    description: Location where game resources live (images, jsons). It is recommended to create custom served folder for this.
+    type: STRING
+  rootScenesPath:
+    displayName: Root scenes directory path
+    description: Data path where game scenes live.
+    type: STRING
+  useCustomPosters:
+    displayName: Use custom game posters
+    description: When enabled the t=start game screen will use provided poster instead of default scene cover. Poster should be named with the following comvention {resourcePath}/{gameId}/poster_{number}.jpg
+    type: BOOLEAN
+ui:
+  requires:
+    - CommunityScriptsUILibrary
+  javascript:
+    - https://cdn.jsdelivr.net/gh/HandyRandyx/stash-plugins@main/utils/fetchInterceptor.js
+    - https://cdn.jsdelivr.net/gh/HandyRandyx/stash-plugins@main/utils/stashHandler.js
+    - https://cdn.jsdelivr.net/gh/HandyRandyx/stash-plugins@main/utils/registerPathChangeListener.js
+    - https://cdn.jsdelivr.net/gh/cj12312021/stash-plugins@main/utils/waitForClass.js
+    - https://vjs.zencdn.net/8.16.1/video.min.js
+    - https://raw.githubusercontent.com/chrisboustead/videojs-vtt-thumbnails/master/src/plugin.js
+    - cyap-min.js
+  css:
+    - chooseYourAdventurePlayer.css
+  csp:
+    connect-src:
+      - https://api.github.com