HTML5 Curation/YouTube Games

This guide will show you how to curate YouTube games using Flashpoint.

Tools

• The YouTube game template, containing an upgraded TweeVee engine and a metadata file with necessary fields filled in, ready to be moved into a curation folder.
• The scrape of game maps in JSON format.
• TweeVee File Generator
• youtube-dl (any other YouTube ripping software will do, but youtube-dl helps with downloading videos with the ID for titles, which is important for generated maps)

Getting Set Up

Firstly, open a new curation and use the following launch command template.

http://youtube.com/*CREATORNAME*/*GAMENAME*/index.html

Next, update the content folder to include the template folder in place of the *GAMENAME* folder and open up the game.tw file. This is where you will define the branches for the game.

Ripping the Videos

Note: This step assumes you are using youtube-dl as your ripper.

Firstly, you will need a list of either video IDs or links that you can paste into a text file. If you are using an automated map, it should come with an accompanying .txt file that contains the IDs you need. Once you have made the .txt file, copy its file location.

Navigate to your "videos" folder in the template and also copy its file location. Paste both variables into the following command. If you are not using thumbnails, you can remove --write-thumbnail.

youtube-dl -f "bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]/best" -o "*VIDEOFOLDERPATH\%(id)s.%(ext)s" --add-metadata --write-thumbnail --batch-file=*TEXTFILEPATH*

This is an example command using a previous curation.

youtube-dl -f "bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]/best" -o "G:\Flashpoint\Curations\Working\107633f0-5aad-47cd-afbc-d09409137b99\content\youtube.com\hasbro\transformersrescue\videos\%(id)s.%(ext)s" --add-metadata --write-thumbnail --batch-file=G:/YouTube/text.txt

Finally, open up your command prompt and use the command you created. This will dump the videos into the correct folder using their ID as the title in MP4 format (for example, dQw4w9WgXcQ.mp4) along with the thumbnail, usually in .jpg format.

Please note that often videos may declare a 403 and stop downloading, or will download very slowly. If this happens, delete all of that specific video's files from the folder including the thumbnail and run the command again.

Once this is done, if you use thumbnails then you should make sure that all thumbnails have been saved as .jpgs, as this is required for the auto-generated maps to find them.

Generating the Map

Note: Because of their automated nature, some maps are likely missing files, or may extend further than their intended game. Never assume a map is 100% perfect, always do a manual check once videos have been ripped and the .tw has been generated.

If you have a JSON map for this game, open the TweeVee file generator and paste the JSON into the box in the far left. At the top of the window, you can also set the "Branch Type". This decides whether the generator uses a map that displays the video's title, thumbnail, or both.

Hit "Start" when done. If you have included titles, this may take a second while the program scans YouTube for the video titles. A message will pop-up indicating that it is done.

Copy the output text that is generated, and paste it into your game.tw file. This is now your starting template for the map.

Understanding the Map

Now you have your map (unless you are building it without a JSON map), it is time to edit the .tw file manually.

Firstly, it is important to recognise what a branch looks like. A branch is made up of three main lines.

1. The branch name.
2. The branch data.
3. The choices.

The branch name always starts with two colons and a space, for example :: dQw4w9WgXcQ. This is the code that the engine searches for when pulling up a new branch.

Important Note: Branch names cannot use special characters. This is why in generated maps, all IDs have had their dashes and underscores changed to dash and under.

The branch data defines the video file name and the point in the video where the choices should appear. These sections consist of two data points in curly brackets separated by a line. The left side contains the filename, and the right side contains the time.

For example, {dQw4w9WgXcQ.mp4|45} would display that video, and would show its choices 45 seconds in. If choices should be displayed over a minute after the video starts, {dQw4w9WgXcQ.mp4|1:45} is acceptable.

Important Note: If most of the videos you have have their choices display themselves a fixed number of seconds before the end (for example, if there is always a 10 second counter) then you can set all times to 0. This will be fully explained in a later section.

Finally, each choice is contained on its own line, and is contained within double square brackets. Like the branch data, this consists of two data points that are separated by a line. The left side contains the HTML code that the game will show to the player when the choice appears, while the right side contains the branch name that the link will send the player to.

For example, this would be the data used for two branches with basic titles as points:

[[Choice 1|gkTb9GP9lVI]]
[[Choice 2|kJQP7kiw5Fk]]

Putting all of this together, the branch for this video would look like the following:

:: dQw4w9WgXcQ
{dQw4w9WgXcQ.mp4|1:45}
[[Choice 1|gkTb9GP9lVI]]
[[Choice 2|kJQP7kiw5Fk]]

Editing the Map

Thankfully, if you generated your map a lot of the work is done for you. The only things you will definitely need to set up is the starting point. Depending on the game, you will also need to set up timings and branch names.

Setting up the starting point is easy. Find the branch in your map that should play when you load and change the first line to :: Start. This lets TweeVee find where to begin, and it does not have to be the first video listed in the file.

Next, it is best to go down the line on the branch list, opening up every video to change the data. For each branch, open up the related video and go to the exact point that the choices appear and pause.

From here, there are a few things you should check. Firstly, check that the branches are in the correct order compared to the video. The choices will be shown left to right. If they are not, reorganise them.

Secondly, make sure the wording of the choices match the video. Some games use different wording for their titles and their choices so it is important to match these.

Lastly, set the timing of the branch to whenever the choices appear. If you find that all or most videos in the game show their choices a fixed number of seconds before a video ends, then you can leave those times at 0 for now.

Editing the JavaScript

Now the map should be set up, so it is time to edit the settings within the engine.js file to fit your game. Thankfully, the variables are all available at the very top of the file in the settings. This can be used to remove some video controls such as skip or rewinding, but the most important ones are at the bottom. Here are the ones you need to pay most attention to.

• SHOW_ONE_OPTION: If this is false, then if a branch only has one option it will never be shown. Instead, the video will simply skip to the option once the video ends. This is useful for games that have connecting videos that don't really require you to click anything.
• CHOICE_DELAY_ON_VIDEO_END: This activates the feature that allows you to pre-set the timing for all videos that have their choice time set to 0. If this is active, then you can use the variable SECONDS_BEFORE_END to select when the choices should appear on these videos. For example, if you set the value to 10, then if a branch has a choice time of 0, the choices will pop up exactly 10 seconds before the end, regardless of how long the video is.

Editing the HTML

The last required edit to make is on the index.html file. You will want to change lines 7, 10, 11 and 126. The first one is the title tag, which is shown on the tab and should match the game's title. The next two are metadata fields that should include the creator and release year. The final field is a H1 tag that should also include the title of the game. This is what it shown when the player first boots, so feel free to include images or paragraphs between the title and the play button.

Filling in the Metadata

There are various quirks to building the metadata for YouTube games that you should be aware of. This is what you should know:

• Logo: Usually this is the opening video's thumbnail, unless the video itself uses a better thumbnail.
• Title/Alt Title: The text on the game's logo takes priority over the video title. However, if they are different, the video title should always be included as an alt title.
• Developer: The name of the channel, and whoever also worked on the game.
• Publisher: Should be set to "YouTube" and any other company that commissioned the game (such as a charity if the game is a PSA)
• Tags: While there is nothing too special about the tags, most YouTube games use "Quiz", or "Adventure", "Choose Your Own Adventure" and either "Live Action" or "Cartoon", depending on the art style.
• Status: All YouTube games are considered "Hacked" as they use a different engine. Assuming the game is complete, "Playable; Hacked" is an acceptable status.
• Source: Should be a link to the first video in the chain.
• Platform: Should be HTML5.
• Notes: Should always include this line: "This game's branching paths have been rebuilt using the TweeVee engine developed by Molleindustria.".
• Original Description: Should be the video description for the first video. Note that YouTube often shortens links. If this happens, you will have to click on the links to get the full URL, which you should paste into the description as a replacement.