Reference¶

This is the reference for Interactive CYOA creators.

While the rest of the tutorial focuses on individual concepts within the creator, this section focuses on real issues and desired outcomes, and walks you through how to achieve it.

Creator¶

Zoom in and out¶

As the desktop application is an Electron app, it is functionally just a website that runs in its own web browser. Because of this, you can zoom in and out of the desktop app by doing Ctrl++ (Ctrl+Shift+=) to zoom in, and Ctrl+- to zoom out.

Open the console¶

In order to open the console, you have to press Ctrl + Shift + I.

Alternatively:

1. In the browser, right click and look for Inspect (Q) or Inspect element
2. at the top of the window on the Desktop app, go View → Toggle Developer Tools.

After that, go into the Console tab.

General¶

Text¶

Make specific text a different colour¶

To do this, simply use inline CSS styling between HTML tags.

For example, this:

1

<span style="color: #ba2323;">makes the text red.</span>

makes the text red.

Add hyperlinks to your CYOA¶

See here.

After that, add hyperlinks as normal:

1

Visit <a href="https://example.com" target="_blank">here</a>.

1

Press <a href="https://example.com">here</a> for more information.

Make secret text that appears when pressing an invisible Choice¶

If you wanted to hide text that only shows when pressing on an invisible Choice, it's quite simply to do. You simply have to lock Addons behind a Selected Choice requirement.

What this looks like:

How to do it:

1. Add a new Addon
2. Add a Selected Choice requirement
3. Put the ID of the empty Choice (that you want pressing and showing the text) into the requirement

If you wanted the text to not show up on the same Choice, you can simply make the Choice require another Choice, and set the filters such that Choices that don't fulfil their requirements are invisible.

Another method is by using Words. Have the Word value be as long as you want, though you might have to use line breaks in order to have multiple lines.

Change text alignment without Private Styling¶

Private Styling has its downsides. However, you can change the alignment (where the text is, such as in the centre or to the left) by using inline CSS like so:

1
2
3

<p style="text-align: center;">
YOUR TEXT HERE!
</p>

The full list of styles available are:

• left – Aligns the text to the left
• right – Aligns the text to the right
• center – Centers the text
• justify – Stretches the lines so that each line has equal width (like in newspapers and magazines)
• initial – Sets this property to its default value
• inherit – Inherits this property from its parent element

Learn more here.

Style¶

Move the other colour stuff to this section.

(TODO) Find out the hex code of a colour¶

Colour in CSS is set in a variety of different ways, such as by a hex code or RGB values.

To learn more, see CSS Legal Color Values and CSS Colors.

If you need help selecting a value, see Color Picker for a simple colour picker, or Color Wheel to easily create complementary colour palettes.

(TODO) Generate a colour palette¶

Use Color Wheel to easily create complementary colour palettes.

There is also

(TODO) Change to a font not in the Creator¶

(TODO) Make text glow¶

(TODO) Change the colour of selected Choices¶

(TODO) Change the colour of Choices that don't meet the Requirements¶

Make Row Backgrounds transparent¶

See here.

Get rid of the extra, repeating Row background¶

You may notice that after you've set your background, your Rows will repeat the Background as well. This is inconvenient if you've set the Background to anything but a simple colour, as it is incredibly obvious and unprofessional.

Here's an example of the repeating background:

Unfortunately, this method deals with Private Styling, therefore:

To get rid of it is simple, just open up Row Settings → tick Use private styling? → Manage Background design → and remove the Background photo on the left side.

Now the background will be whatever colour it is usually. To make it transparent, see below:

(FIX GIF) Make the Row Background transparent¶

Go into Row Settings → Use private styling? → Manage Background design → and turn down the A (Alpha) slider on the Background column (far left).

Make the Point Bar icons white for darker CYOAs¶

You may wish to make your Point Bar icons white if you have a particularly dark CYOA, making it hard to see the icons.

To do so, you have to hack your css/chunk-vendors.58637379.css file¹.

Pre-made file method¶

Download this fixed file here, and replace your existing css/chunk-vendors.58637379.css file with it.

Manual method¶

Open it inside of a text editor, and search (Ctrl + F) for .theme--light.v-bottom-navigation .v-btn:not(.v-btn--active) you will find the entry you need to change right after it, the color:rgba(0,0,0,.6) one. The first three 0s are the RGB code, and the last one is the alpha/transparency level (1 = normal, 0 = invisible, 0.5 = transparent). This option corresponds to the default colour.

The next thing to search for is .v-item-group.v-bottom-navigation .v-btn.v-btn--active. You will find another color entry that should look like color:inherit. Change this to color:rgba(255, 255, 255, 1) to make it fully white. This option corresponds to what colour the icons are when they have been pressed.

(TODO) Make a group of invisible Choices in a Row not take up any space¶

Can apply to the Row itself too.

Private styling stuff. Compare a normal Row with the one for the World button in the CYOA below, and point out the differences.

See https://infaera.neocities.org/cyoa/OverpoweredIsekai/ for a working example.

Whole CYOA¶

Changing the page title¶

In order to change the title of the tab in the browser, simply edit index.html.

Look for:

1

<title>CYOA</title>

One title format is {CYOA name}: Interactive, but whatever works for you is fine.

Changing the page icon¶

Changing the icon of the page's tab is simple, all you need to do is add the following code to your index.html file, just below the <title> tag:

1

<link rel="icon" href="/link/to/icon.jpg">

(TODO+EX) Tabs / Table of Contents Menu¶

To make a Tabs menu

(TODO) Show Points Menu¶

Use this if you have a lot of Point Types. This allows you to give control over to the player about which Points show up in the Points Bar.

Much like the above, create a Tabs menu, but instead of each option opening a Row, use their Point Type to hide the choices.

This is especially useful for mobile users (which make up a surprising amount of ICYOA players), as their screens are usually smaller and thus can't see as many Point Types in the Point Bar.

Show a loading progress indicator¶

See here.

Make the Background completely static¶

A static background, as opposed to a continuous or overlapping background, is one that scrolls with the user, perfect for backgrounds that do not repeat perfectly.

An example of a continuous background is the Worm V3 Revised interactive (shown below). No matter how far you scroll, the background stays in the exact same position.

It was first used in the Jedi - Guardian of the Republic Interactive CYOA, where the background fixes are attributed to u/LOLLOL12344.

CSS Method #1¶

This and Method #2 are the preferred methods.

Download static_background.css, and put it anywhere in your project's folder. I recommend putting it in a folder called css, which should already exist if you have the Viewer.

Then, put this in your index.html in the <head> section:

1

<link rel="stylesheet" href="./css/static_background.css">

Change the href to wherever you've put it.

CSS Method #2¶

If you don't want to rely on a folder, you can simply put it straight into your index.html file in <style> tags. Put this in the <head> section:

1
2
3
4
5
6
7

<style>
  .pb-12 {
    background-size: cover;
    background-position: center;
    background-attachment: fixed;
  }
</style>

JavaScript method¶

This is not the preferred method, but still works regardless.

In order to make a background static, if you don't have the progress indicator simply add this code to the <body> section of your index.html:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

<div id="indicator">
<script>
  {
    let _XHR = XMLHttpRequest;  XMLHttpRequest = class XHR extends _XHR {
      constructor () {
        super();
        this.addEventListener('progress', e => {indicator.innerText = " Loading data: " + (!e.total ? `${(e.loaded/1024**2).toFixed(1)} MB` : `${(100 * e.loaded / e.total).toFixed(2)}%`)});
        this.addEventListener('loadend', () => {indicator.innerText = "",document.getElementsByClassName("pb-12")[0].style.cssText += "background-size: cover;background-position: center;background-attachment: fixed;"});
      }
    }
  }
</script>
</div>

If you already have the progress indicator, you can simply add this line right after the this.addEventListener('progress'…) line:

1

this.addEventListener('loadend', () => {indicator.innerText = "",document.getElementsByClassName("pb-12")[0].style.cssText += "background-size: cover;background-position: center;background-attachment: fixed;"});

This will modify your background to become static!

Make your Background fade in¶

Add this to a <style></style> block in your index.html, or in your own CSS file:

1
2
3

.pb-12 {
  transition: background-color 300ms linear;
}

This will mean that when the background is launched for the first time (and any other time it changes) it will fade into that colour.

Make the Background a different colour every 20% of your CYOA¶

This is how to make your a different colour every 20% of your CYOA you scroll. For the programming-savvy, you may be able to hack this code to change for your use-case.

If you're looking for a way to do this at arbitrary points, such as with each Row (as opposed to each 100px or so), check out the section below this one.

Put this into your index.html:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

<script>
  var bg_color = document.getElementsByClassName("pb-12")[0];
  var colors = ["white", "red", "black", "blue", "pink"]
  var _rows = document.getElementsByClassName("row")[0]

  function find_change_positions(elem) {
    var elem_dimensions = elem.getBoundingClientRect()
    var elem_absolute_pos_start = elem.getBoundingClientRect().y + window.scrollY
    var elem_absolute_pos_end = elem_absolute_pos_start + elem.getBoundingClientRect().height
    return elem_absolute_pos_end - (window.innerHeight / 2)
  }

  var change_positions = []
  for (let i = 0; i < _rows.childElementCount; i++) {
    change_positions.push(find_change_positions(_rows.children[i]))
  }

  window.onscroll = () => {
    for (let i = 0; i < change_positions.length; i++) {
      if (window.scrollY < change_positions[i]) {
        bg_color.style.backgroundColor = colors[i - Math.floor(i / colors.length) * colors.length]
        break
      }
    }
  }
</script>

Make the Background different for each Row¶

This will allow you to dynamically change the background of your CYOA depending on arbitrary placement of <div> tags.

Here's a demo:

To get started, download these files:

• dynamic-background.js
• dynamic-background.css (Optional)

The CSS file is optional, but contains a starting point to base your own background from.

Place the JavaScript (.js) file in the js/ folder of your Viewer, and your CSS (.css) file in the css/ folder of your Viewer.

Then, place this in your index.html in the <head> section to import the files:

1
2

<link href="css/dynamic-background.css" rel=stylesheet>
<script src="js/dynamic-background.js"/>

In the css file, copy this code for each of your different backgrounds:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

.your-id-here {
  /* To set the background to a colour: */
  background-color: #900;
  /*
    Or alternatively, to set the background to an image:

    (Note: this image can be a local image, in which case just put "image.png" 
    or "images/cat.png" instead of a full HTTPS URL)
  */
  background-image: url("YOUR URL HERE") !important;
}

.your-id-here could be something like a colour: .red-bg, or maybe just the name of your section: #perks.

If you wanted the colours to fade together in a transition, see the Make your Background fade in section in this tutorial, and apply that code in this CSS file.

In your actual project.json in the ICC, add this to the very top of your Row's Text:

1

<div id="your-id-here" class="bg"></div>

Leave "bg" as-is.

After all that, your CYOA should not change depending on which Row is in focus!

(TODO) Making the CYOA embed on sites¶

Wanted to know how to make your CYOAs have a little embed that shows information when posted to sites such as Discord and Twitter?

You don't need to include all of these, they are all optional.

Simply paste this code in the <head> section of your index.html:

1
2

<!-- A description of your CYOA or site -->
<meta name="description" content="Your Description">

Combining with a title, it will produce this:

See more here.

Make the CYOA show up on search engines¶

SEO—Search engine optimization—is the process of making your site look better to search engines, so that it will appear higher in the search results.

I recommend giving SEO a Google search if you wanted to know more.

Simply paste this code in the <head> section of your index.html:

1
2
3
4
5
6
7
8

<!-- Your CYOA Titles -->
<title>Example CYOA: Interactive</title>
<!-- A description of your CYOA or site -->
<meta name="description" content="Your Description">
<!-- Your username -->
<meta name="author" content="Your Name">
<!-- Tags for search engines to pick up on -->
<meta name="keywords" content="CYOA, Interactive CYOA, Living God Interactive">

See more here.

(TODO) Change the Scrollbar Colour¶

Add this to your index.html file, in the <head> section:

1
2
3
4
5
6

<style>
    * {
        scrollbar-width: auto;
        scrollbar-color: rgba(251, 115, 52, 1) rgb(60, 75, 80);
    }
</style>

Alternatively, put it in any .css file you have.

Download someone else's Interactive CYOA¶

There are multiple methods of doing so.

Using IntCYOAEnhancer¶

See here.

Accessing the project.json directly¶

As you may know if you are familiar with the Viewer layout, the project.json file containing the code for the ICYOA is located in the same folder as the index.html. Using this logic, if an ICYOA was located at mycyoa.com, then you would be able to access the project.json at mycyoa.com/project.json.

(TODO+LINK) Embedded in JavaScript¶

If the above method fails, they could have embedded their project.json directly into their Viewer's app.c533aa25.js.

To get the project.json out, simply follow the opposite of these instructions.

Change project.json to a different name¶

There could be many reasons why you want a different name than project.json. Perhaps you're working with different versions of the project, or perhaps your web host doesn't allow .json files, or perhaps you just don't like the name.

Regardless of the case, you must go into your js/app.c533aa25.js file, and do a Find and Replace (Ctrl + H) in a text editor. Set Find to project.json and Replace to your new name, such as Beta-v2.json.

Choices¶

(TODO) You may only pick X options¶

Use Allowed Choices.

(EX TODO) You may only pick X options from an arbitrary group¶

Similar to the above, except these choices are not required to have been from the same Row.

You do this buy creating a unique Point Type that is unable to go below 0, and is also hidden. Each choice in this arbitrary group costs 1 of these points.

This can be useful compared to the above if you wanted to have a dynamic

Choice requires another's Choice¶

See here

(TODO) Hide a choice if it doesn't meet the requirements¶

Simply use filters.

(TODO) Disabled Choices via Selected Choice¶

If you have some choices that have prerequisites/requirements, then having them require those requirements will enforce that users don't cheat, and follow the rules.

(TODO) Making Choices Invisible¶

There are two ways to make a Choice invisible, depending on what you want:

1. If you want a Choice that is merely meant for functional purposes (i.e., it does some logic in the background), simply make the Choice title and text empty, and it will effectively render it invisible.

   Best used with an invisible Row and at the end of the document.

2. If you want to make choices that don't fit requirements disappear, then you can solve that using filters. We discuss that below.

   Note

   Instead of making choices invisible, consider merely blurring them or dimming them such that they're visibly unable to be selected. This way, users will be able to tell there's a potential Choice there, and they simply need the requirements.

   If you still want to make Choices invisible, continue on ahead.

Choices that don't have their requirements can be made invisible using filters.

(WIP) Chaining Invisible Choices¶

There may be times where you have to do something like activate a function more than once, but the Choice which is selected does not allow that, such as wanting to change multiple Words.

A way to bypass that, is

(TODO) Dynamically change Allowed Choices number¶

You can dynamically change the

Make a Choice only able to be selected once¶

This will make sure that once they select the Choice it cannot be reselected².

This is what it'll look like once you're done:

What you do is:

1. Make a Point Type just for this option
2. Hide the Point Type
3. Set the Point Type to 1
4. Set a += More or Equal requirement on the Choice you want to affect
5. Select the Point Type you created, and set it to 1
6. Add a Score setting the Score to 1

And you're (functionally) done! You can reset it in the creator by clearing your selected IDs.

But we can go further. In the private styling we can setup disabled Choices so that they look like they've been selected, so this can only be used if the Row is explicitly for Choices you don't want to be taken back, otherwise the styling would be inconsistent.

Do this like so:

1. Turn on Private Styling
2. Manage Filter Design
3. Change the Filter on Choice that is missing its required to the same as the filter above it, matching it

And then we get this:

There is — as of yet — no known method to detect whether the Choice has been pressed because it actually stops being selected as soon as you press it, with the bug being that it appears and acts disabled.

(TODO EX) Make a Requirement based on a Choice that can be selected multiple times¶

To do this, you simple have to:

1. Create a hidden point type
2. Make sure it's set to 0
3. Add a Score to it
4. Set the score to increase the Point by one
5. In the Row, Choice, or Addon you want to detect the multiple selected choice, make a:
   • More Than 0 Requirement, if you wanted to detect if the Choice has been increased more than once
   • Less Than 0 Requirement, if you wanted to detect if the Choice has been put in the negatives

IDs¶

(TODO AN EX) Navigation with ID / Title list¶

ID / Title list as helpful way of navigating your way through a large CYOA – showcase JRPG Traitor

Using the See ID/Title List option in the Sidebar allows you to quickly navigate through your CYOA.

(TODO) Reusing IDs¶

Interesting fact: Setting multiple things to the same ID allows you to activate one through the other

Requirements¶

(TODO) Logic Gates and Requirements¶

'All of these are selected' requirement¶

There is no such requirement within the ICC at this moment. To emulate it, however, is simple. Just add more than one Selected Choice requirement, and it will ensure that you have each and every one selected.

'None of these are selected' requirement¶

As above, simply add a Non-selected Choice requirement for each ID that must not be selected.

(TODO) 'Not all of these are selected' requirement¶

Functioning as a NAND gate.

(TODO) 'All of these are either selected or non-selected' requirement¶

Functioning as a XAND gate.

(TODO) 'One of these is selected and another is non-selected' requirement¶

Functioning as a XOR gate.

Points and Scores¶

Hide Point Types¶

Go to the Sidebar → Open Features → Manage Points and find the Point Type you want to hide.

In the Id Needed to Show field, type something you would never use as an ID, such as HIDE_ME. As an object with your chosen ID should never be selected, the Point Type should be ID.

(EX TODO) Display Hidden Point Types when a Choice is selected¶

Do the same as Hide Point Types, but instead of an ID that won't be selected, purposely choose the Choice's ID that will show the Point Type.

(TODO) Limit how many of an arbitrary group can be selected¶

I find it particularly useful in hidden point types that determine how much of a thing you’re allowed to select

This uses hidden Point types.

(TODO) Making discounts¶

Discounts can be made using requirements.

Get a list of Point Types¶

To do this, first, open the console.

Then type this:

1

document.querySelector('#app').__vue__.$store.state.app.pointTypes.forEach((el,i)=>{console.log(`[${i}][${el.name}]: ${el.startingSum}`)})

It will output a list of Points by their name and their value.

It should look like this:

1
2

[0][Good Karma]: 21
[1][Bad Karma]: 0

Change how many points I have¶

This is a hacky way on how to change it as a player.

There are two methods:

1. Use the IntCYOAEnhancer script to change the values, or
2. Manually edit it in the console

We'll be showing the second solution here.

To do this, first, open the console.

Then, get a list of Point Types. Find the ID associated with your Point Type on the left most side surrounded by square brackets. Keep a note of that number.

Then type this:

1

document.querySelector('#app').__vue__.$store.state.app.pointTypes[0].startingSum = 1000000

Replacing:

• 0 with the ID of your Point Type
• 1000000 with whichever number you desire.

Images¶

(TODO) Separate images from the project.json¶

You can easily separate images from the project.json file.

To do this, you simply go into Save/Load Project → Download Finished Project With Separate Images.

This will give you a zip file called hello.zip, which you can and should rename to something more helpful.

Extract the zip, and inside you should find your project.json with a hugely reduced size, and all the images you've uploaded separated in an images/ folder.

Next, move the project.json file and the images/ directory into the same directory as your Viewer.

Allow <img> tag¶

The ICC doesn't allow using <img> tags by default, but this is bypassed in the modded Viewer, available here.

Words¶

Changing Words with Choices¶

You can change the value of Words using an Object function.

To do so:

1. Go into the Edit Row menu
2. Go down to the Choice you want to change the word
3. Open the Functions drop down menu
4. Select Word will be changed to something else at select

You should have this screen now:

Id of word that will change¶

This is where you select the exact Word that you will change.

By pressing on this, it will open a dropdown menu of all the Words, so you don't need to remember the ID of your Word.

Will be changed to this on select¶

This is what the value of the Word will change to when the Choice is selected.

Will be changed to this on deselect¶

This is what the value of the Word will change to should this Choice be deselected.

There are two strategies here:

1. If you want to return to the default one that was set in the Words menu, simply put the option here.
2. If you want to make the change permanent (at least, until something else changes it), then put the same value as the above input in here.

For this tutorial, we are going for the former strategy:

Putting it all together, this is what it looks like:

One thing you could put here instead of a favourite game could be a narrator remarking on a player's choice. For example:

Ooh you picked #choice did you? Very interesting indeed…

Dynamically display Points inside a Row, Choice, or Addon¶

This is useful if you wanted to remind the user how many points they have, and may be useful if you don't desire to have a Points Bar.

To achieve this, simply go into Open Features → Words, and create a Word using the ID of your Point type.

Buttons and Variables¶

(TODO) Generate a random number¶

(TODO) Pick a random choice in a Row¶

(TODO) Hide a Row behind a button¶

Use a toggleable variable and use that ID in a selected choice requirement

(ADD VIDEO) Make a DnD-style 1d20 skill check¶

This is how to make this:

This example uses a 1d20 dice, but you could possibly hack this to produce other methods.

1. Create a Point Type to be used for this only
   1. Set the Id Needed To Show option to something random to hide it from the Point Bar
2. Create the Row that will house the Roll button
   1. Switch on Button?
   2. Select other
   3. Tick Random or Variable? on
   4. Select Only Unselected choices?
   5. Select Button can only be pressed if no choices is selected? only if you want it to be a one time thing
   6. Go back to the Row edit menu
   7. Change Allowed Choices to 1
   8. Create a base Row for the value of "1"
   9. Under that Row, add a Score with the value of "-1" to add to a Point Type
   10. Select the dummy point type you made above
   11. (optional) if you want to display the result later on
       1. To display the result of this choice, create a Word
       2. Change the ID to something unique like #encounter-roll, and set the text to something like 0 or (Roll first). This is the text that is displayed before you have rolled, so it doesn't matter.
       3. Select Functions → Word will be changed to something else at select.
       4. Change Will be changed to this on select to 1, this will change for each cloned Choice
       5. Change Will be changed to this on deselect to 0, don't change this when cloning
   12. Clone the Choice 20 times (the amount of sides the die has)
   13. Go through each Choice and update the Score and (if you had set it above) Word number as is needed
   14. (optional) if you want to display the result and did the previous steps: use #encounter-roll in your text, e.g. "You rolled a #encounter-roll!"
3. Create the Row that will house the Results
   1. Select Non-activatable?
   2. Create as many Choices as you want messages
   3. Set requirements for both. Use a += More Than requirement for what the baseline the roll should achieve to succeed.
   4. For the display of failure, use a - Less Than requirement for the same number as above, and a More Than equal to 0 (as this is the default, and you don't want to count it as a failure yet).

(TODO) Make a DnD-style skill check plus an arbitrary number N¶

Create a button that picks a random Choice only once and permanently¶

This makes it so that once you press the button not only does the button disappear, but you will be unable to deselect the chosen option.

This is good if you wanted a truly random and risky part of the CYOA.

Groups¶

(ADD EXAMPLE) Display a list of all Choices selected within a Row or Group¶

This can be useful if you wanted to give a summary at the end, with Rows like "Companions" only showing the selected Companions.

To do this:

1. Create a group
2. Add the Row to the Group or add all Choices you want to the Group
   1. The latter is is used, for example, in situations where you want to lump Choices across multiple Rows—but not all of them—into the same Group. A situation this could happen is filtering by something other than the Row/Section category. Displaying all female characters whether a Companion or Enemy, for instance.
3. Create a new Row
4. Enable Selected Choices?
5. Enable Selected Choices from Group Id

Et voilà! It should be working as expected.

HTML¶

Formatting¶

Headings¶

Text¶

Allowed HTML tags¶

The following are the default allowed tags that are rendered with the Viewer:

Allowed attributes¶

Attributes provide additional information about HTML elements.

CSS¶

Allowed styles¶

Here is a list of allowed styles:

Allowed style tags¶

See the HTML tags that allow the style attribute here.

JavaScript¶

Comments