Overlay for quick CYOA playing. No more spreadsheets!
The design is minimalistic, so make sure to at least skim through the usage section, or refer to it when confused
(also, check for tooltips on unmarked checkboxes).
Features
- An overlay (toggled from userscript menu) to keep track of points/choices in any CYOA (both can be color-coded for convenience);
it gets transparent when unfocused (unless this is turned off), and supports filtering/readonly mode for viewing final build
- Builtin support for Imgur, ImageChest, ImgBB, Cubari, and standalone images (+my CYOA viewer);
should work seamlessly on any other site (just add it in script settings to the user matches, e.g. https://cyoa-site.domain/*)
New in v0.9.1: support for FunnyJunk
- Capable of saving build to/syncing from the storage, syncs stored data on tab refocus (to share play state across multiple browser tabs);
additionally, a ‘preset’ can be exported/imported to avoid having to type in all the choices from scratch
- New in v0.8: sync with URL hash (allows to share/bookmark builds without relying on storage; equivalent of the IntCyoaEnhancer feature)
- CYOA mode toggle button for Imgur, ImageChest & FunnyJunk (wide images browsing)
New in v0.8.3: enforced rendering of full-size images (not the lower-quality preview ones)
New in v0.9.1: a page tracker (on Imgur: scroll through all pages before use – see CYOA Mode section for details)
- Menu actions to open the gallery in other pages: Imgur/ImageChest -> Cubari, Cubari -> Imgur/ImageChest, and anything
other than Cubari -> Viewer
(Cubari doesn't keep URLs available, but you can switch back to Imgur first if that's where the gallery is from);
New in v0.7: Reddit gallery threads -> Viewer
New in v0.8.3: Cubari support for ImageChest & Viewer; old & guest mode Reddit gallery threads -> Viewer
Note: the script was developed under Firefox (which is better suited for CYOA browsing either way), with Tampermonkey script manager.
Chrome (and browsers based on it) was tested for general compatibility but I could've missed an issue if it's sufficiently obscure.
Firefox users: you may want to enable (toggle to true) the value dom.forms.select.customstyling in about:config, to enable colors in dropdowns
Usage
With exception for CYOA mode button, the userscript is activated via userscript menu (in case of Tampermonkey, click on the Tampermonkey
button in the browser toolbar to find it). To open the CYOA calculator overlay, pick “Toggle overlay” action. (Additionally, unloading
the overlay is done with the same menu action; all the state is reset upon unloading, including the storage connection.)
When loaded, the overlay can be found at the top right corner of the screen; it's transparent when not hovered by the mouse cursor,
to prevent getting in the way of reading the CYOA, and can be minimized at any time.
Overlay header
At the top of the overlay (which can be found in top-right corner of the screen) is a header/toolbar.
- Rightmost element (top-right corner of the overlay) is the
> button (tooltiped as Collapse) which minimizes the overlay;
when minimized, the overlay is replaced with a single < (Expand) button which restores it back to the original size.
You can also minimize it by pressing Escape key.
- Leftmost element (top-left corner of the overlay) is a checkbox tooltiped as
Pin; when toggled on, it prevents the overlay
from going transparent upon losing mouse cursor focus. It also prevents minimizing the overlay by Escape key (but not by > button).
- Next to the Pin checkbox is a view switch button; it switches to Choices view when on the Points view, and to Points view otherwise.
- Remaining (central) part of the toolbar depends on the active view.
Points view
This is the initial view, as well as the “navigation hub” of sorts for other views. It allows you to browse/manage your point types.
- The main area contains the list of point types (ordered lexicographically), each displayed with current/initial amounts.
(By default, there's one type named
points, with initial amount of 0.)
By clicking on any of these point types, its line gets switched to the edit mode, which allows you to delete it, or modify its name,
initial amount and color (defaults to white). To close edit mode, you can press × button or Escape key (the overlay won't get minimized
unless you press it twice; but if you're typing in a value, make sure to hit Enter first to apply your changes). You can also stop editing
by switching to another point type (by clicking on it), or by switching to another view.
- Below the main area, you'll find a large
+ (Add) button; use it to add new point types.
Note that you can't create a point type by an already existing name (nor rename to one) – such an action will be rejected.
- The header of Points view contains the view title (
Points) along with a Build button showing the name the current build was saved as
(or <unnamed> in italics if the build wasn't saved to storage). Clicking on it will open the Builds view.
Note: deleting the point type removes it from all choices as well. Renaming the point type also updates all choices that use it.
Choices view
This view is opened by clicking Choices button in the Points view. It contains the list of choices you've picked (along with those you
deselected without deleting); you can alter it, change your selection, filter by selection, and view your build in read-only mode.
- The main area contains the list of choices (ordered lexicographically), along with selection inputs and the
edit button.
Clicking on the name of a choice toggles the selection; this can also be done by clicking the checkbox to the left. When the choice is selected,
the checkbox will be followed by a ∧ button; clicking it turns on multi-selection (setting the amount to 2).
Setting the amount below 2 will turn off multi-selection for the choice.
Clicking edit switches on edit mode for the choice, same as for points; it allows you to delete the choice, or modify its name, color, and
points effect (cost/bonus). Same rules apply to editing/closing as for the point types.
- Below the main area, you'll find a large
+ (Add) button; use it to add new choices.
Note that you can't create a choice by an already existing name (nor rename to one) – such an action will be rejected.
- To the left of the
+ button is the Show selected checkbox; it filters out deselected choices.
To the right of the + button is the Read only checkbox; it disables choices/selection editing.
(When it's on, the + button is replaced with the Grouping dropdown, which allows to alternate between grouping modes.)
You can use these together to view your current build (e.g. for copy-pasting somewhere else).
- The header of Choices view contains current amounts for each of the point types (ordered lexicographically); you can differentiate between them
using color coding and smart naming schemes (to enforce convenient ordering). Also, the point type name for each of them can be viewed as a tooltip.
- New in v0.6: when not in read-only mode, the header contains an
Extra controls checkbox button; it toggles a panel with additional controls:
- D&D-style RNG/dice roller (NdM+K => roll M-sided die N times and add K to the result)
- Build comment textbox (will be displayed at the bottom in read-only mode)
- New in v0.8.4: when not in read-only mode, the top of the body contains a simple Search filter (limits displayed choices to those containing the entered substring, case-insensitive)
Note that any complex CYOA rule (like a single-time cost/bonus for a multi-selection choice, or synergy effects), especially when making a ‘preset’,
will likely require you to create additional ‘virtual’ choices that indicate such effects; as a convention, I suggest making it grey-colored and
naming it after the option, appended by rule/effect description in braces ({}) – e.g. Choice name {+other choice}.
Also note that grouping in read-only mode works based on a simple pattern match: group name: choice name.
Builds view
This view is opened by clicking Build button (displaying the name of the active build or <unnamed> if none) in the Points view.
It contains the list of stored builds along with the current one; each stored build can be exported as a file, and the current state can be stored as
a build (or overwritten by importing/loading a build).
- The top of the main area contains controls for the current state. If it's not stored as a build, it contains buttons
Import (which loads a build from
a file) and Save (in storage) (which allows you to choose a name for the build); if the state is stored as a build, the state controls contains the
Export button (which saves the build as a file), the build name tooltiped as Rename (clicking it will allow you to change current build name),
and the Delete button (which deletes the build from the storage and unloads the overlay).
- The rest of the main area contains a list of stored builds (ordered lexicographically), excluding the current one. Each row contains the same controls
as the current build for a stored state, except that deleting one of these builds doesn't unload the overlay, and only the current build can be renamed.
Additionally, when current state isn't stored as a build, it can be discarded by clicking an existing build name – this loads the build from storage.
- The header of Builds view contains the view title (
Build) along with the selected/total choices counter (this makes import result evident).
Additionally, at the right end of the header (before > button) is the Fast sync (multi-tab) checkbox (hidden when the build isn't stored).
Use it when playing a CYOA across multiple tabs (e.g. if you opened each page as a separate image); it enables fast-sync mode, so that the updates are
loaded from storage every 5 seconds – this allows freely switching between tabs of the same CYOA without having to micromanage your build or being
forced to keep it within one tab. [no longer necessary, sync is done on tab focus]
New in v0.8: Also at the right end of the header, a Hash/Unhash button can be found; you can use it to store current state in the URL hash
(similar to IntCyoaEnhancer feature – do note though that if the host website also uses URL hash these might conflict and/or override one another).
The URL hash is updated whenever the state changes, until you toggle off the overlay or click Unhash.
It is read when the overlay is toggled on; if it contains a valid state value, you'll be offered to import it (doing so will also reenable Hash mode).
Note that stored builds are saved to the storage on every build change, and even if you haven't enabled fast-sync the build will be synced occasionally
(once per 5 minutes instead of per 5 seconds). The only way un-sync (unlink?) the overlay from a build is to unload the overlay (via “Toggle overlay”).
Likewise, you can't export your build without storing it, and can't overwrite a stored build directly by loading or importing another.
Also, unless you're using Firefox, changes in storage made in Private mode aren't retained when closing the browser.
CYOA mode
Certain sites used for hosting CYOA images (image gallery sites) aren't well-suited for browsing them: they clutter their interface with UI elements
unnecessary for image viewing, and the images themselves only take up a small part of the screen, regardless of their actual size. (And if you click
on the image, you get a full-screen preview… which doesn't help at all when the image is 10000px long.)
In case of those supported by this userscript (Imgur and ImageChest), it adds a CYOA button to the top-left corner of the screen; clicking on it
toggles “CYOA mode” which removes all the clutter and makes the gallery area (almost) full-width. The state of the button is retained for the site
(so after enabling CYOA mode in an Imgur gallery, all Imgur galleries will be loaded in CYOA mode until it's toggled off again).
(Also, I suggest setting 120% page zoom for CYOA browsing.)
New in v0.8.3: improved Imgur support (full quality images, disabled switching galleries by Left/Right Arrow keys)
New in v0.9.1: added a page tracker (slider for page selection)
Note for Imgur: before using the slider, scroll through all pages! (I.e. drag the slider from first to last tick one-by-one, or just hold down PgDown after loading the page first).
Due to a bug in the site code, for any page that Imgur hasn't loaded yet, Imgur will mess up positioning of all the subsequent pages!
Open in Cubari/Imgur/ImageChest
Cubari is a manga viewing app adapted for browsing image galleries; some of the few sources it supports are Imgur & ImageChest.
This userscript adds a menu command “Open in Cubari” for Imgur/ImageChest galleries, which causes the browser to open the respective Cubari URL in a new tab;
and for Cubari pages supporting Imgur/ImageChest, a menu command “Open in Imgur” (“Open in ImageChest”) is added.
(I suggest enabling limit-width, top-to-bottom single-page layout with page gaps on, and with page-selector pinned on the left in Cubari settings…
and of course collapsing the sidebar as well.)
Open in Viewer
CYOA Viewer is a CYOA viewing app I've made at some point, the main feature of which is that it
displays loaded images in full-width (limiting their width to 100% of the screen; though it can be changed to 150%, 200%, 300% or 400%).
Though I guess the CYOA mode mitigates most of the reason for using it (in case of Imgur/ImageChest galleries).
This userscript adds a menu command “Open in Viewer” for most supported sites (except for itself and Cubari, but including standalone images),
which causes the browser to open the respective Viewer URL in a new tab.
(Opening from Cubari isn't supported due to technical difficulties in obtaining URL lists; also, if you open an individual page – either as
a standalone image, or in Imgur/ImgBB, – “Open in Viewer” will load Viewer with only the currently opened page.)
In case of standalone pages, you can either download them and use “Open” button of the Viewer, or compose a Viewer URL on the
URL generator page (type the title and URLs into respective inputs, and click the first generated link).
New in v0.8.2: on the Viewer page, there's an option to switch to CYOA Viewer v2 (a version that supports making an "interactive" overlay) and back to v1; and on both of these pages, there's an option to open the URL generator with the data from the current Viewer URL.
