Welcome to the Plotato Engine User Manual

Note: This document is still a Work-In-Progress.

The Plotato is a free and open sourced, visual novel game engine, written as a Single Page App using Python (Brython), HTML, CSS and a minimal amount of Javascript.

It was designed to run from the players hard drive without the need for a server, both on desktop and mobile (Android) devices, but it can run just as well from a remote server (as a static website, oe PWA) or embedded in a Electron app (with some extra steps).

The name Plotato is a portmanteau of the words 'plot' and 'potato', as it is focused on quickly and efficiently developing complex plots and compared to 'full fledged' game engine it has the functionality of a potato, being able to do little else beyond displaying images and blobs of text.

Plotato has been strongly inspired by the popular Ren'Py engine, but only in the way the game is presented to the player (full-screen image with a bit of text at the bottom and maybe some pc/npc sprites in between).

Some programming skills are required to make a Plotato game, but usually You won't need to write programs nor functions and you won't need to design algorithms.

You may need to learn how to write Python expressions for example to save some information for later use, like: save.end_of_shift = get_hour() + 8

You may need to learn how to write conditions: (if) get_hour() > save.end_of_shift

You will definitely need to learn how to call Python functions: set_tce('pool_party', 12, 15, 'map_home', 'remind_party')

For customizing the look of the game you will need to know at least some CSS, but the game uses bog standard, verbose CSS in a everything-is-a-class paradigm. In most cases you can just use right-click anything, bring up the developer tool, mess about with the styling until you get the element to look as you want it to, and copy/paste the changes back into style/default.css.

All the codebase for the engine is provided in plain text format. Nothing is minimized, nothing is obfuscated, every single function and class is documented. The engine has about ~400 lines of HTML, ~3000 lines of Python and ~1200 lines of CSS - including comments and blank lines (+2x as much for all the tools). One could read and understand all of it in one afternoon.

The engine is distributed under a lax, permissive free software license. One can use, copy, modify, and/or distribute this software for any purpose with or without fee, with the only restriction being that a copyright notice isn't removed. There is no GPL poison.

In this section you can find a brief description of most of the key features of the engine. You will learn what they are, what they can be used for and how to actually use them.

As the name suggest - background images are the images in the background. In this document the background image may also be called the main image or just image.

You can have only one background image per node (scene) and what image gets displayed is defined inside the node. Details about how to add an image to a node are described in the Plot Nodes section and in the Plot Editor section.

Images should be exactly 1280x720 and saved in any format supported by browsers (png, jpg, webp, etc). If you need your images at a different resolution you may need to change how PC and NPC images are show, how and where map markers are shown and probably also change the behavior of overlays.

The background image is always rendered behind the player and NPC images, it is also usually rendered behind the overlay, but that can be changed in the overlay specific css (using "z-index: -1;" css property).

Background images are not affected by Filters.

The background image use the 'main_img' css class.

By default when a new image is show it is gradually ( in 0.5 of second) faded in on top of the old/existing image and once this animation is complete the old image is removed.

The images are not cached or pre-loaded in any way other than what the browser (and/or server) provides for any image.

Parallax images where primary designed to show scrolling (background) images with a parallax effect - that is where objects in the distance move slower then objects nearby.

Parallax images are scrolled across the viewport either horizontally or vertically.

To get a parallax effect you need to have at least two images, with the background image proportionally smaller compared to the foreground. But you are not limited to just two images, you can add as many as you like - but keep in mind that each additional image may degrade performance.

This feature can also be used to show only one image - in that case it will just be scrolled across the viewport.

To add a parallax image to a plot node you need to call the parallax_imgs() function (add it as a cmd)

Example in editor:

Parallax effect example (notice the clouds in the background scrolling at a different rate compared to the foreground):

The term Player Character (or PC for short) refers only to the paper doll avatar, an image or series of images displayed on top of the background image.

By convention the player controlled character is always displayed on the left side of the screen and the NPC (Non-Player-Characters) are displayed on the right. This arrangement can easily be changed by editing the style/default.css style sheet (.pc_img and .pc_imgs classes).

Unlike the NPC image, the PC image is dynamic by default. It's not a single image but a stack of images depicting the characters body, clothing, facial expression and hair.

Depending on the flavor/version of the engine there can also be additional layers like tattoos, piercings and overlays. You can add and remove these additional layers as you feel fit, just add (copy/paste) another img tag in the 'pc_imgs' div. The order in which the img tags are added to that div matters - this is the order the images will be drawn (so nude/base body should go first, before clothing and facial expressions).

The PC also supports svg filters - by default there are 2 such filters provided, the 'default' filter draws a shadow behind the images (respecting transparency) and the 'night' filter tints the avatar blue-ish (and also draws a shadow). This is a useful feature that allows to recolor the avatar at runtime. Both PC and NPC are set up in such a way that changing the filter changes both NPC and PC images (without affecting the background) - more on that later.

There is an option to overlay a image on top of the player avatar, this overlay can also use mix-bled-modes as supported by css.

The individual parts/images of the avatar can by programmatically replaced not just once but in such a way that each time the avatar is show the replaced parts will show the correct new image (for instance to replace one hairstyle with another.)

Another dynamic aspect is the clothing system, but that is described in a further chapter.

The PC system is deeply embedded into the engine, it's data files and editor. Usually all that the game creator needs to do is to select the facial expression for the avatar in the editor and the engine will do the rest. Selecting no expression means that the avatar should stay hidden.

Non-Player Character ( or NPC for short) refer to the avatar image of the NPC.

By convention the NPC character is always displayed on the right side of the screen and the PC is displayed on the left. This arrangement can easily be changed by editing the style/default.css style sheet (.npc_img class).

The NPC image are static and there is only ever one NPC image displayed at the same time.

The NPC supports svg filters - by default there are 2 such filters provided, the 'default' filter draws a shadow behind the images (respecting transparency) and the 'night' filter tints the avatar blue-ish (and also draws a shadow). This is a useful feature that allows to recolor the avatar at runtime. Both PC and NPC are set up in such a way that changing the filter changes both NPC and PC images (without affecting the background) - more on that later.

The NPC system is deeply embedded into the engine, it's data files and editor. Usually all that the game creator needs to do is to select the name of the NPC from the editor.

DataStore is the interface the game uses for persistent data. The default implementation uses localStorage as the backend, but other mechanisms can be used.

If for some reason the engine can't access the browsers localStorage (write and read back values), a fallback implementation is used, but in that case the user needs to manually save and load and all unsaved progress is lost.

By default when the game starts the following DataStore are created:

• cfg (game configuration)
• save (saves and current game state)
• inventory (items/clothes in pc's possession)
• quests (current quests status)
• rollback_* (as above, but used for rollback)

DataStore implements both a dictionary like interface as well as 'doted' access. For example if you want to store a value for later, you can use save.some_value = 14 or save['some_value'] = 14
There's also a add_item() function that has the same functionality:
save.add_item('some_value', 14)

Because of the way the doted access is implemented there are some restricted key names that you should not use. These are:

• __init__
• inner_dict
• __inner_dict
• __getitem__
• _name
• db_storage
• __getitem__
• __setitem__
• add_item
• set_list
• get_list
• append_list
• del_from_list
• is_empty
• items
• clear
• add_flag
• has_flag
• get_flags
• remove_flag
• remove
• to_string
• from_string
• __contains__
• __getattr__
• __setattr__
• __delitem__

DataStore also has a default (zero) value for non-existing keys. This is made so that you can test values in the storage without the need to first test if the values exist. For example, you can do if save.some_value: do_something() even if you never used save.some_value or save['some_value'] (save.some_value will evaluate to 0)

You can test if values have been set using the 'in' operator.
if 'some_value' in save:

You can iterate over the values like you would with any dictionary using the .items() function.
for key, value in save.items()

DataStore can save value types that can be serialized to JSON, that is:

• strings ('some value')
• integers (42)
• floats (3.14)

It is recommended to store boolean values (True, False) as integers (1, 0) and None values as an empty string ('').

DataStore also allows for storing some more complex data structures. The functions add_flag(), has_flag(), get_flag(), remove_flag() allow setting multiple values (flags) for a single key. For example:
save.add_flag('visited_places', 'beach')
save.add_flag('visited_places', 'school')
save.add_flag('visited_places', 'cinema')
if save.has_flag('visited_places', 'beach'): has_been_to_beach(True)
The flag functions are implemented using a set.

One can also store and retrieve lists using set_list(), get_list(), append_list().

API:

A Plot Node (or just node for short), is the basic, atomic part of the games plot. Or in other words - it defines what is shown in the game window and knows what node to show next (how to traverse the node graph).

All nodes have names and each node name must be unique (there can't be two nodes with the same name). The nodes themselves are just collections of optional key - value pairs (that means a node can theoretically by just a name).

The keys in a node have special meanings and are made to help in writing common tasks and actions without the need of writing custom Python code for each node.

name

This is the unique identifier. Each node must have one, and each name must be unique.

next

For 'normal' nodes this points to the next node that will be shown one the user clicks to advance.
The value should be the name of an existing node.
For nodes that show any kind of special interface (shops, wardrobe) the game will advance to the next node once that interface is closed.
Nodes with branches, choices or jumps should not have a next value.

pc

If this key exists, upon visiting the node the PC avatar will be shown.
The value defines what facial expression will be used for the PC.

txt

This is the text displayed upon visiting the node. If a node has a next node defined it should also have something under the txt key

The value may be interpreted as a Python f-string if there are any curly brackets in the text ('{' and '}'). For example:
I have {save.money} dollars in my pocket.
or
I have {str(save.money)+'dollars in my pocket' if money>0 else 'nothing!'}

Because of the way this feature is implemented special care must be taken when using ' and " symbols. You might need to replace ' with ` in some words (eg write can`t not can't) - the game will reverse this and players will still see "can't".
You might not want to use manual line breaks as the text is evaluated per line.
It is advisable to check if the text is evaluated correctly each time you use this feature.
It is not recommended to add functions with side effects to the evaluated text (use cmd for that).

npc

If this key exists, a NPC image will be shown for this node. The value is the url for the image to use.

img

If this key exists, a background image will be shown for this node. The value is the url for the image to use.

eval_jump_to

If this key exist, its value will be evaluated (using the Python eval() function) and the value returned will be used as a node name to jump to.
For nods that have a eval_jump_to value only the img and cmd key are used - everything else is ignored.
The value of eval_jump_to is not evaluated by the editor and it is commonly used as a way to introduce discontinuity in the plot graph (so that only some and not all nodes are show in the preview).

cmd

This key holds a list of commands (Python statement) to be executed. They are executed in the order they appear and before any other changes to the game window are made (before the background image is changed, and before pc and npc images are shown).

choice

Choices are explained in a later chapter. This key holds a list of lists where each outer list represents a choice that the player can make and each inner list has the condition, label and target node name.

branch

Branches are explained in a later chapter. This key holds a list of lists where each outer list represents a choice that the player can make and each inner list has the condition, and target node name.

The Editor:

When using the editor (dev/plot_edit.html) the currently selected nod is always displayed on the right side of the window. Editing a node is just a matter of filling in the form and/or clicking on some buttons.

The plot graph is the collection of all the plot nodes and their connections. It is stored as a JavaScript object in the file data/plot.txt and the dev/plot_eitor.html is the recommended way to edit it as it shows how the nodes are connected (using arrows and colors) and also gives some hints about the content of the nodes using symbols (hovering over them shows even more informations). This is how the plot looks in the editor:

A Choice is the basic way in which a player can interact with the game. From the players perspective a choice node presents itself as one or more buttons in the game window and clicking on any one of them moves the plot forward in a different direction (or sometimes it's an illusion and all choices lead to the same outcome.

From the creators point of view a choice can have multiple entries and each one has 3 elements:

Condition

A choice condition is a Python expression that needs to evaluate to either True or False (or return a truthful value, like 1 or 0, None, ""). The expression is evaluated at runtime, when the player reaches the choice node and if its return value is True the choice is presented to the player (in the form of a button).

It is important that at least one condition in a choice node always evaluates to True, else the player might get stuck (softlocked) without any option to progress the story.

If a choice should always be visible to the player, one should write True or 1.

Label

The label is simply the text on the choice button.

While the game can handle relatively long labels, the text shouldn't be needlessly long.

Target

Target is the name (id) of the plot node where the game will jump to when the player clicks on the particular choice.

Choice as seen in game: Choice node in Plot Editor:

A branch is another way to control the flow of the plot. Unlike a choice, a branch offers the player no interaction and selects the next node based on the conditions programmed by the game author.

Just like the choice node a branch has target and condition fields, but no labels. A choice node also shouldn't have any text because as soon as the player reaches a branch node the conditions are evaluated and the game jumps to a new node.

A branch node can also be used to execute commands. In some cases you would need to wrap commands using the execute_once() wrapper in case the player saves at the particular node and the commands get executed each time the game is loaded.

The game will instantly jump to a target node (after executing the commands), if there is just one entry in a branch node (preferably with a True condition), effectively turning the node invisible to the player and adding a safe place where the author can put commands without the fear of exploits.

Condition

A branch condition is a Python expression that needs to evaluate to either True or False (or return a truthful value, like 1 or 0, None, ""). The expression are evaluated at runtime, in the order they appear in the plot graph (from top to bottom, in the editor). If the first entry evaluates to False, that entry is skipped and the next entry is evaluated. This process is repeated until a condition evaluates to True (at least one conditions should always evaluate to True!).

A special value random_branch can be used in place of a condition. If it's present, the game will select one of the branches at random. This special mechanism expects all of the entries in a branch node to have the random_branch condition or none at all. The games makes some behind the scene manipulations such that the same target node won't be selected twice in a row or even again until all other nodes have been visited. It's not purely random.

Target

Target is the name (id) of the node where the game will jump to once a condition is evaluated to True.

Branch node in Plot Editor:

Jump is another way to control the flow of the plot. Unlike choice and branch, jump has only one field - the 'eval_jump_to'.

Like with choice and branch the python expression in the evel_jump_to field gets evaluated at runtime when the player reaches the jump node, but the key difference is that the expression must return a valid node name (id).

While a jump node can be used for all sorts of advanced shenanigans, it's primary use is to introduce gaps in the plot editor. The editor will not evaluate the provided expression and will not draw any nodes leading away from a jump node.

It is strongly advised to put jump nodes at every plotline end to minimize the amount of nodes displayed at one time, especially when having multiple, concurrent plotlines.

To make a 'static' jump to another node from a jump node just type in the name of the target node in quotes (eg. "some_fun_node" or 'some_fun_node').

Jump node in Plot Editor:

Commands are snippets of code (Python expressions), executed when the player reaches the node and one node can have multiple commands.

Commands are executed in sequence, in the order they appear in the plot node. They are executed before anything else - before images are shown, before choice or branch conditions get evaluated, before jumps are made.

It is important to note that commands get executed each time a node is visited - this includes situations where the player loads a game. To prevent this behavior one can use a 'invisible' branch node with just one branch (as described in the branch section) or use the exec_once().

The exec_once() wrapper keeps track of what commands where executed for a particular node and prevents commands from being executed again, if the node has been already visited by the player. Note: exec_once() require the command to be passed as a string eg. exec_once('save.money+=100')

A full list of commands can be found both at the end of this document as well as in the editor (under the API tab).

Details on how to write a valid Python expression are beyond the scope of this document. Use Google to find a tutorial about Python if you need further help writing Python code.

cmd in Plot Editor: Auto-hints for cmd in Plot Editor:

Filter refers to a SVG filter applied to both PC and NPC images. These allow to change the appearance of these elements at runtime without the need to make multiple images.

By default only 2 filters are provided with the engine 'default' and 'night'. The first one only draws a drop shadow around the sprites and the later also uses a color matrix to tint the sprites blue.

To change the filter use either svg_filter('default') or svg_filter('night') commands (in a nodes cmd).

The filter will not automatically switch back to the default state, so always make sure to switch back when you are done using a non-default filter.

Custom filters can be added, one just needs to add a filter element inside a svg tag and give it a unique id. That id can later be used in the svg_filter() function. Details on how to write a svg filter are beyond the scope of this document.

PC with 'default' filter: PC with 'night' filter:

Overlay is a image (or effect) displayed on top of the background image and both PC and NPC sprites.

To add an overlay to a scene (node) use the overlay_img()command.

Multiple overlays can be added one on top of another, just pass clear=False to keep multiple overlays on the screen when adding overlay layers.

The img_class can be used to create various effects. Rain, fog, smoke, moving background, disco lights to name a few. The details on how to use CSS to achive such effects are beyond the scope of this document.

Overlays are not cleared automatically, so just like with filters, one needs to remember to manually clear a overlay once it is not needed. To clear all overlays just call overlay_img() with no arguments.

The engine provides an autosave feature. Whenever the player visits a node, the game checks if a autosave flag has been set on the node (by default, the Plot Editor sets this flag on all nodes), and saves the name of the current plot node along with some extra informations (last know pc stat, npc, image, etc).

The game also stores a save version, this is meant to help in the event of errors, where some extra steps are needed when loading from an older (bugged) version. The seve version for new saves is first set in init_new_save() and later updated whenever the player loads a game (in the restore_last() function).

If you need to make your own contingency procedure for loading older version saves look to the implementation of the restore_last() function.

Rollback is a feature that allows the player to move back to a previous choice and try different paths.

Each node only holds informations on where to go next and procedures (commands) on what to do once the node is reached. In many cases the commands executed upon reaching a node cannot be easily reversed - for example, a simple command like save.something=7 could be impossible to reverse as we have no informations about the previous value of 'save.something'.

The rollback feature is implemented using somke and mirrors. Whenever the player reaches a choice node, copies of the current save, inventory and quest DataStore are made and when the player decides he wants to roll back to his last choice, these copies replace the current save, inventory and quest. It's an automated quicksave.

A modal UI widget is one that blocks access to all other UI elements, it is usually a dialog box or pop-up.

The engine has some helper functions that make it easy to create custom modal dialog prompts, but it should be noted that this is an advanced feature and should not be used lightly, as it blocks the player from accessing the game controls.

Creating a modal usually requires to provide a list of html elements and since there is no convenient way to do that from within a nodes cmd, it is not recommend to create modal popups using the cmd interface.

Modal example as seen in-game:

Quests refer to tasks that the player is given. They are visible to the player as a to-do list, and it's up to the game author to best decide how and when to update this quest-log.

Clothes are a visual representation of what the PC is wearing. It the default setup only the Player Character is dynamic and capable of wearing clothes.

Slots are used to determine what the PC can wear at the same time, in the default configuration these are:

• accessory
• top
• bottom
• underwear_top
• stockings
• underwear_bottom

The player can only have one item in any of the slots and each piece of clothing can only occupy one slot (even if visually they take up multiple slots - like a dress covering the body from neck to knee).

Clothes are drawn in reverse order so first underwear_bottom, then stockings, underwear_top, bottom, top and finally accessory.

For example if the PC has an item is both underwear_bottom and bottom slots - the item in underwear_bottom will be drawn first and on top of that the item from the bottom slot will be drawn.

It is important to note that 'no item' is also a clothing item in the clothing system, so you may need to create blank items for every slot with no images.

To help determine what kind of clothing the Player Character is wearing a tag system is used.

Every clothing item can have a list of tags associated with it, some of them may have a special use or meaning, but in most cases it's up to the author to give these tags a meaning.

The function get_equipped_tagset() can be used to check what tags the currently worn clothes have.

Because the first game developed using the Plotato engine was a female protagonist visual novel with strong sexual themes, the engine has an inherent sluttiness rating system. The details on how exactly that system works are complicated and will probably need a few paragraphs all to themselves - for now it's enough to say that such a system exists and can be easily removed or disabled if needed.

The engine provides a shop and wardrobe interface that lets the player decide what he/she wants to wear (see 'Shops' below).

The set_clothes() function can be used to give and put on clothes on the player avatar. give_clothes_by_tag(tag) can be used to give multiple items at once, but the preferred way to add and remove items is by using the inventory DataStore.

inventory.add_item('some_item_name') will add 'some_item_name' to the players inventory (without equipping it) and inventory.remove('some_item_name') will remove the 'some_item_name' item (without un-equipping it, so never remove items in use).

API:

Shops are basically pre-defined list of clothing items. The prices and other stats of items are defined in data/items.txt so the data/shops.txt file only tells the game what the shops sell.

To open a shop (show the player the shop ui) one needs to call the shop(shop_id='some_shop') function.

The shop and wardrobe system share some of the UI elements, with the difference being that the wardrobe screen has player customizable outfits (sets of clothes) where the shop would have a shopping cart panel.

The function change_clothes() that brings up the wardrobe UI is just a wrapper for shop(shop_id=None).

The engine takes care of remembering what item are bough and sold even if the player closes the game mid shopping. It will also prevent the player from leaving the shop if the value of the items in the shopping cart exceeds the player's available money.

Wardrobe UI in-game: Shop UI in-game:

The map system uses a static background image for the map and dynamic markers/point of interest (poi). The player can move freely between the POIs on the map by clicking on any of the markers while the map screen is visible.

The map offers map events (random encounters) that can trigger when moving around the map, either based on chance or custom trigger conditions (see 'Map Events' section below).

By default the map expects 3 images for the background - one for the day, one for the night and one for dusk and dawn (img/map.webp, img/map_dark.webp and img/map_dusk.webp).

To take the player to the map screen use the show_map() function. It is recommend that a node using this command has no images, pc, npc nor a next node defined.

In cases where the author wants to limit the available choice of POIs or show special POIs that would normally be hidden, one can use the additional parameters in the show_map() function.

POI

The points of interest (POI) are stored in data/map_poi.txt, where each POI has it's label, icon, target (plot node name/id), name and coordinates defined.

POIs are by default hidden to the player and need to be manually added to the list of known places before the player will be able to see any of them. This is best done using the add_poi('poi_name') function, where the poi_name is the name of the poi as defined in data/map_poi.txt.

If needed POIs can also be removed (or at least hidden from the player) using the del_poi('poi_name') function.

Map as seen in-game:

In most cases, when a player clicks on a map marker the game will simply jump to the target plot node defined in data/map_poi.txt for that POI, but that may not always be true.

Before jumping to the target node the game first calls the _get_map_event(from_poi, target_poi) function to check if there is a map event. Depending on the version of the engine there may or may not be hardcoded map events that may send the player home if wondering late at night or without any pants on. When making Your own game You most likely need to at least look into the details on how that function is implemented.

In cases where You never want to trigger any map events when the player clicks on a map marker, you need to set up Your POIs in a specific way. If a POI target does not start with a 'map_' prefix all map events will be ignored whenever the player clicks on that POI.

Apart from the hardcoded events _get_map_event(from_poi, target_poi) may also return random events or dynamic map events.

Dynamic map events

Dynamic map events can be set at runtime using the set_map_event( target, from_poi=None, target_poi=None ) function. The 'target' argument must always be provided (it's the target node name/id), but both from_poi and target_poi are optional.

If just from_poi is provided the event will trigger when the player leaves that POI heading for any destination.

If just the target_poi is provided - the event will trigger when arriving at the given POI.

If both from_poi and target_poi are provided - the event will only trigger when the player moves from the from_poi to the target_poi.

There can be multiple map events set, but obviously only one can trigger at any given time. Their priority is as followed:

1. Event with no from_poi and no target_poi
2. Event with from_poi equal to current location and no target_poi (happens as PC leaves a place)
3. Event with both from_poi and target_poi that match where the PC is going from and to (happens on route)
4. Event with no from_poi but with target_poi equal to where the player is going (happens when PC arrives)

Dynamic map events are always one-shot, as removed as soon as they are triggered. If the need arises to manually delete a event that didn't trigger yet - one can use the remove_map_event(target, from_poi=None, target_poi=None)

The game checks for dynamic map events after checking the hardcoded events and before checking random events.

Random Map Events

Random map events can be defined in data/map_events.txt.

The value saved in save.map_event_chance determines how often random map events can happen. Any value between 0 and 100 are valid and 0 means never, 100 means always

When the engine decides that a random map event should happen, it takes the list of all possible events, removes the ones that don't match the current game state (wrong time of day, wrong from or to nodes, wrong clothes, failed custom conditions, etc) and picks one of the events at random, using the individual events chances as weights.

Each time a random event triggers it's weight(chance) gets reduced and so the more a event happens the less likely it is to happen again. There's also a mechanism that prevents the same event from triggering twice in a row.

Time is internally stored as the number of hours from the start of the game.

Each in-game day is divided into 6 periods (time-of-day):

• 0 Night (00:00 - 03:00)
• 1 Morning (04:00 - 07:00)
• 2 Noon (08:00 - 11:00)
• 3 Midday (12:00 - 15:00)
• 4 Afternoon (16:00 -19:00)
• 5 Evening (20:00 - 23:00)

The in-game clock can be advanced by one or multiple hours or one can skip to a desired time-of-day.

Special care must be taken when advancing the clock to a specific time-of-day, as not to skip to the next day by accident (eg. skipping to noon when it's already midday or later could move you to the next day skipping over both night and morning).

API

Time Critical Events (TCE) are events that trigger at a pre-defined time, when the player travels using the map (or at some specially constructed plot nodes).

If a TCE is set, the in-game clock will not advance past the time when the event should happen (unless using set_hard_datetime() or manually changing save.time).

Out of map node setup for TCE

If you're using the TCE system and have places in the node graph where time is skipped forward, but you don't return to the map screen afterward - you might want to set up some extra nodes that will check for time critical events after visiting a node that calls progress_time().

Checking for events

Make a Branch node with one of the conditions being get_tce() is not None. If this condition is evaluated to True, you have a TCE to go to - but before pushing the player to the map screen, you might want to check if the event should maybe take place where the player currently is.

Checking event destination

If you know that a TCE is schedule to happen now, you can check where it should take place and compare that to the current location: get_tce(arg='map_poi') == 'some_poi_name'. You can also use the save variable 'current_location', that gets updated each time the player moves via the map - of course if the player never moved via the map, moved about using some other way, or had a random encounter while traveling - the 'current_location' may not always be reliable get_tce(arg='map_poi') == save.current_location.

Manual trigger

If you determined that the player already is where the event should happen, you can trigger the event using a jump node (eval_jump_to) with: get_tce(arg='target')

Clean up

TCE are not automatically removed if not triggered from the map, so always make sure that you call remove_tce() in the first plot node of the event.

API:

The engine provides a way to play back audio using the browsers audio player.

The current implementation only allows to play one sound at a time and it is recommended to provide audio in mp3 format, because support for other audio formats varies from browser to browser.

While the volume can be changed programmatically, it is advised to let the end user decide at what volume to play to audio.

Note: Some (if not all) browsers will not allow to play audio until the player interacts with the page (clicks a button), therefore it is impossible to automatically play background music on the first screen (main menu) when the game first loads.

If run in a browser/operating system that provides Text-To-Speech capabilities (using the Web Speech API), the engine can perform text to speech synthesis.

The TTS implementation is not designed with ease of access in mind. It will not read button labels, it will not read actor names, it will not give descriptions of scenes nor images - it will only read what the characters would say.

TTS is designed so, that each actor in the game can have it's own distinct voice. Unfortunately there isn't one set of voices available on all systems, so if a player wants to use this feature, he needs to manually assign voices to all the actors in the game.

The data file 'data/voices.txt' stores a list of known actors under the name 'known_voices'. For every item in that list the game will create a widget allowing the player to set a voice for that one actor. The widget will not display a name, but a small portrait to avoid potential spoilers. The game expects the portraits in 'img/portrait/' saved as .webp files with the name of the file identical to the name of the actor.

Actor names

The game expects the first line of any text in a txt field that ends with ':' to be a actor name eg. Some NPC: - if such a pattern is detected, the game turns that first line into lowercase letter and strips any non-alphanumeric characters to create a internal representation of the actor name - using the previous example Some NPC: would get turned into somenpc.

If there is a item on the 'known_voices' list in 'data/voices.txt' that matches the actor name as constructed above, then the game will synthesize text-to-speech using a voice that the player assigned to that actor.

Speaker Alias

If there is no known voice that matches the actors name, the game checks another variable defined in 'data/voices.txt' - the 'speaker_alias'.

'speaker_alias' is a dictionary that holds alternative actor names. If we had 'somenpc' in 'known_voices', but we also want a npc named Some Other NPC: to also use that name, we would have to add 'someothernpc':'somenpc', to the 'speaker_alias' dictionary.

Default voice

If the game can't find a voice for the current blob of text, a default voice is used. That default voice is called 'default' and it also can be customized by the player (unless removed from the 'known_voices' list - do not remove 'default' from the 'known_voices' list).

In-game TTS setup:

The engine allows for custom content mods to be loaded.

Mods are Python scripts that are executed at the end of the game initialization. They are stored in the 'data/mods.txt' data file and can be loaded using the dev/mod_manager.html tool.

Because of how Python works, mods can change anything and everything. Change functions, modify data, add or remove widgets etc.

Mods can be potentially dangerous to the end user, but since the game is running in a browser provided sandbox - the risk is minimal. Mods can redirect to malicious sites or prompt the user to save executables to the hard drive, but can't do much without active user input or interaction.

Before You start writing your own game You should take a minute to customize a few elements in the index.html file. All the places you need to edit are marked with '#CHANGE_HERE' in a comments, so even if the line numbers change in future version, these elements should still be easy to find.

The HTML

The changes needed to make in the markup part of the engine are quite simple and focused around credits and copyright notices.

You will most likely want to add your name or company name to the page meta-data, copyright notice at the bottom, change the title and perhaps add or change some buttons on the title screen.

Here are some screens taken from a text editor showing what to look for and what to change. Details on how to write and modify HTML code is beyond the scope of this document.

Meta-data. Add and/or change whatever you need.

Game specific style sheet. If you have some custom css (for example for overlay effects or animations) you can add it to a separate file so as no to mess with the original engine stylesheet. Deleting it and putting everything in one file also works.

Game title. Self explanatory.

The monetize div is meant to hold clickable buttons, that would take the user to outside webpages or display some modal screen with extra info on how to support the game creators. You can remove these if you don't intend on using this feature or add your own. Note that you will need to write your own CSS styling for your custom buttons and bind events so that something happens when the user clicks on them - you'll see how a bit lower.

The copyright notice is just a bit of texted displayed at the bottom of the page. Here you can customize what it says. Note that by default the engine will add a version number at the end.

Python

Changes in the python script may be a bit more challenging, but you don't need to know how to write a python program, just how to change some letters.

Data Storage. This is the interface for saving and loading game states from the browsers memory (local storage). There's more info on this in later parts of this document. On Chrome based browsers all games (and apps) running locally (not from a web server) share the same space, so to avoid one game (app) from overriding data from another we use a prefix to store the data under a unique name. The default prefix is usually 'plotato_' but as show on the screen this may vary. Replace the string 'plotato_demo_' (or 'platoto_') with a prefix that will be unique to your game. Remember to keep it between the quotation marks.

Default values for new save. init_new_save() is a function that is (should) be called when a player starts a new game. Here you should reset (clear) the data in old saves and set default values for the rest of the game. The example below shows how to set up things like starting date and time, money, items (clothes), known places, etc.

Here, on the first line you can see how the buttons in the monetize div (mentioned above) are bound to functions. Or in other words - what happens when the user clicks on any of them. doc['buymeacoffee'] tells the script that we want to do something with a element with the id='buymeacoffee' and the rest of the line defines what we want to do with it. You don't need to understand all of it, just knowing it will open a URL (website) under the address 'https://www.buymeacoffee.com/sharkinahat' is enough. To make your own button open the website you want just replace the URL (and/or element id).

The next few lines show how you can set up a modal (full-screen pop-up). The details how a modal works are described further in this document.

Title screen. This is the part of the script that defines what is shown when the game starts. It has reasonable defaults, but if you want to name your plot nodes differently or add other buttons on the title screen - here is the best place to do so.

These are the basic files that the engine uses, along with a brief description of their purpose (in brackets).

• audio (music/sounds)
• brython (Brython implementation)
  • brython.js
  • brython_modules.js
• data (data files)
  • items.txt
  • map_events.txt
  • map_poi.txt
  • mods.txt
  • plot.txt
  • shops.txt
  • supporters.txt
  • version.txt
  • voices.txt
• dev (developer tools)
  • bug_tool.html
  • item_editor.html
  • item_maker.html
  • make_datalist.py
  • mod_manager.py
  • plot_edit.html
  • shop_editor.html
• font (fonts)
  • fa-solid-900.ttf
  • monofonto.ttf
• img (images)
  • ...
• mods (third party mods)
• style (CSS stylesheets)
  • default.css
• index.html (main game file)

The engine makes use of a few data files, and while technically all of these files contain (or may contain) code, we will refer to them as data.

The data files use a txt extension, but they all are in fact JavaScript source files. Because of the limitations of Brython, one can't (easily and reliably) read the content of arbitrary files, therefore the data is stored in easy to import JavaScript files.

The .txt extension is used because some browsers are funny about saving .js files

items.txt

This file stores the clothing in a dictionary named 'items'. It's data structure looks like this:

 var items = {
    "item_id":{
         "name":"Some Item Name",
         "img":"img/pc/debug_sack.png",
         "slot":"top",
         "tags":['clothes_top', 'clothes_bottom', 'some_other_tag'],
         "slutty":0,
         "value":100,
         },
    "other_item_id":{
         "name":"Some Item Name",
         "img":"img/pc/debug_sack.png",
         "slot":"bottom",
         "tags":['clothes_bottom', 'some_other_tag'],
         "slutty":5,
         "value":10,
         },     
	};         

map_events.txt

This file defines events that can occur randomly when traveling via the map.

var map_events = [
    {'from':'', 'to':'', 'time_of_day':'', 'chance':0, 'slut_x':0, 'eval':'True', 'target':'', 'clothes': [] },

];                		

map_poi.txt

This file defines all points of interest on the in-game map, including hidden ones.

//  ['label',              icon',  'target',          'name',           x,    y ]
//id:0                     1       2                  3                 4     5
var poi = [
    ['Explore the City ', 'f4d7',  'map_explore',     'explore',        1245,  88],
];                		

mods.txt

This is a file automatically generated by the mod_manager.html and controls what third party mods are loaded by the game. It contains the source code of loaded mods and might not be very human-readable.

plot.txt

The main data file containing the plot graph.

var notes = "";
var plot = {
    "pre_new_game" : {
        "txt" : "The game uses an auto-save system, starting a new game will {RED('ERASE ALL AUTO-SAVES')} (but not manual savefiles)! Do You want to start a new game? ",
        "no_save" : 1,
        "choice" : [["True", "Start New Game", "new_game"], ["True", "Cancel", "back_to_main"]],
        "cmd" : ["music('like_the_synth')", "parallax_imgs(('img/parallax/class_l0.webp', 'img/parallax/class_l1.webp', 'img/parallax/class_l2.webp'))"]
    },
    "new_game" : {
        "txt" : "Would You like to see a short tutorial going over the basics of the User Interface? ",
        "img" : "img/title/title_free.webp",
        "choice" : [["True", "Show Tutorial", "tutorial_1"], ["True", "Skip", "prologue_jump"]],
        "cmd" : ["init_new_save()"]
    }
};  

shops.txt

This file lists what items are available in what shops.

var shops = {
    "dress_shop":[
        "dress_sun_lila",
        "cone_dress",
        "santa_micro_skirt"
        ],
    "other_shop":
        ["some_item",
        "pants"
        ]
    };        

supporters.txt

This file contains the text for the 'credits' slideshow.

                    
var credits = ['CREDITS',
                'CREATED BY:\nShark in a Hat',
                'STORY BY:\nShark in a Hat',
                'ART BY:\nShark in a Hat',
                'PROGRAMMED BY:\nShark in a Hat',
                'POWERED BY:\nThe Plotato Engine',
                'POWERED BY:\nBrython'
                ];    

version.txt

This little file only contains one value - the current version of the data files. It's used to display the game version, but apart from that it's up to the author to decide how it's used, changed or tracked.

 var data_version = '0.8.dev';   

voices.txt

This file lists aliases for actors and what text-to-speech voice the actor should use.

var known_voices = [  "default",
                "emily",
                "ben",
                "fnpc",
                "mnpc"];

var speaker_alias = {   "boy": "mnpc",
                        "disclaimer": "default",
                        "femalevoice": "emily"
                    };    

The engine comes with a set of useful tools, most of them are written in Python/Brython and run as local .html files right in the browser, but some are standalone Python scripts that you need to run via a Python interpreter.

dev/plot_edit.html

The Plot Editor is the most important tool of all, as the plot file can easily grow to multiple megabytes in size for larger games and it's simply impractical to edit a file of that size by hand.

The Editor has 3 main elements - the toolbox in the top left corner, the node editor on the right and the plot graph taking up the rest of the space.

The Toolbox

When first starting the editor, the toolbox will always be collapsed and looking something like this:

Clicking on the toolbox will expand it (and this is true for all the widgets in the editor that have that little triangle at one side)

'Start from...' tells the editor what node to draw at the top of the node graph, or in other words -where to start from.

The dropdown here will list all the nodes that don't have a direct parent (ancestor), these are nodes that the player will probably move to through a jump node (a node with eval_jump_to).

It is recommended not to create cycling reference in the first node of a subplot. The first node can lead to as many other nodes as you like, but no node should connect back to that starting node.

If you would create a plot graph such that 'node_a' leads to 'node_b' and 'node_b' leads to 'node_a' neither of these nodes would be listed in the 'Start from...' dropdown and both could become inaccessible in the editor.

Filter nodes...

This tool allows to one to write a custom rule and filter out all the nodes that fit the rule.

For example if you need to find all the nodes that use the image 'img/npc/dude6.png' you could write: npc == 'img/npc/dude6.png' and click FILTER to get a list of nodes in the dropdown below (selecting an item from the dropdown will draw the graph from that node).

The function doing the filtering brings in the fields from each node into the local scope. You can use any of them directly

• text
• next
• pc
• npc
• img
• eval_jump_to
• branch (as a list)
• choice (as a list)
• cmd (as a list)

Python

Here you can execute your custom Python script right in the editor.

The top text area is meant for your script and the bottom one is where the log() function prints it's output.

This is a feature meant for advanced users and might be hard to use for anyone not intimately familiar with the inner workings of the editor.

Notes

This is a text input area for your notes. You can write anything you want here, it will be saved in the plot.txt file.

Save Vars

This section list all nodes that write anything to the save DataStore and groups them by the variable name. It is not always perfectly accurate.

Quests

This section lists all the nodes that add or update the quest log.

Mods

LOAD MOD

Clicking this button will allow you to load a previously saved mod. Because of the flexibility of mods not all of them can be guaranteed to load properly.

The editor executes the mod in a separated namespace and retrives 'data.plot' from that namespace as modified by the mod. If a mod is implemented in a way that relies on 'data.plot' to have specific keys and values, that mod may fail to load in the editor.

The recommended way to create plot mods is to update 'data.plot' in place eg.:

mod_plot = {} # the data to be inserted
for k,v in mod_plot.items(): 
    data.plot[k] = v 

WRITE MOD

Clicking this button will save the changes you've made to the plot as a mod file, that can be loaded via the mod manager.

Config

In this section you can change the position and font size of the Node editor. Usefull on mobile and touchscreens where one can't just drag or resize the Node Editor panel.

WRITE

Clicking this button will generate a plot.txt file and ask the user to save it (depending on browser and configuration, it may ask for a name and destination or just write the file to a default location)

Node Editor

The node editor is located on the right side of the window, but it's position can be changed by simply clicking on the header (part of the editor that says --EDIT NODE--) and dragging the whole thing to wherever you want.

Just like the toobox the node editor can be minimized/collapsed.

Most input fields in the node editor provide hints. These can be names of existing nodes, image filenames, npc images or sometimes Python functions or snippets

The editor also supports drag and drop for input fields that require a node name (next, targets). You can drag a node from the node graph into a input field to automatically fill it out with the name of the node.

Node Type

The editor has 4 types of nodes:

• Normal
• Choice
• Branch
• Jump

A normal node is any node that has a 'next' field, a choice node is one that has a choice field, and so one.

The engine does not make this kind of distinction, but since a choice node shouldn't have a next field and a branch node is not supposed to have text, it is only logical to have some sort of mechanism in the editor to minimize potential user errors.

Switching between the node types is done by clicking on one of the radio buttons with the nodae type names. This will hide or show fields appropriate for the given node type.

It is important to note that this is just a editor feature, and the underlying plot node can have all the fields filled no matter what type of node the editor thinks the node is.

The editor will not try to guess the type of a node when editing an existing node, so the fields visible when first vieeing a nodes properties may be wrong and you may need to manually switch the node type to see the content of the nodes fields.

Common elements

Depending on the type of node, the editor may display a different set of widget, but no matter what type of node you are creating or edditing, all of them share some common elements.

Draw Graph from This Node button

As the name suggest, pressing this button will draw the plot graph from the current node.

name

name is the unique identifier of a node, it's id, the key under which it is stored in the plot graph.

If you edit a node and change its name, the changes will be saved under this new name, leaving the original node unchanged.

It is up to the author to keep the names unique, as the editor will override any existing nodes without asking if there are any node name conflicts.

cmd

Commands are common to all nodes and one node can have a virtually unlimited number of commands. Clicking the '+ New CMD' button will add another input field where you can type in your Python expressions.

Save Node button

Clicking this button will save all the changes you have made to the node and re-draw the plot graph. The editor will also create new, empty nodes if you've specified next nodes or target nodes that don't exist.

The changes are saved in the browsers memory, you still need to save the changes to a file (write).

Remove Sub-Plot button

Clicking this button will remove the current node and will also try to remove any and all of it's descendants.

Remove THIS node button

This will remove the current node as well as removing all reference to it from it's direct ancestors.

In-Game Autosave tickox

In the rare occasion you want to disable autosave for a specific node, you can un-tick this tickbox.

Clone subplot

This is an experimental feature that lets one clone multiple nodes at once and insert them right back into the plot graph under different names.

NODE TYPES:

Normal node

A normal node has the following fields:

• name (required) - unique id of the node
• next - (usually required) name of the next node in the node graph
• PC - state/look of the player avatar/paperdoll (hidden if blank)
• txt - (usually required) Text visible to the player
• npc - NPC avatar/paperdoll
• img - background image
• cmd - commands run when the node is shown

All fields except the name are optional. The name needs to be unique, if you save a node using a name that some other node already has - the editor will override the existing node without asking.

The 'name +1' button will automatically generate a new name for the next node based on the current node name. If the current node name ends with a underscore and a number (like some_node_69), the name for the next button will be generated by adding +1 to that trailing number ( some_node_70). For node names without numbers the generated next node name will have '_1' at the end (some_node ==> some_node_1.

The next field can be skipped only if calling show_map() in the cmd or some other similar function that provides an alternative way of moving to other nodes.

The txt field should be blank only if calling shop() or change_clothes() or some other function providing an alternative way of progressing to the next node. It should also be left blank when using show_map().

Note: In normal gameplay the player needs to click somewhere on the text panel to progress to the next node, so if thereis no text, there is nothing that the player can click.

The npc and img fields have a built-in preview option, one just needs to expand that field.

Choice node

A choice node is very similar to a normal node, with the only change being that the next field is replaced with the choice fields.

The choice fields is an array of 8 rows of 3 input fields each. These represent the conditions, labels and targets for each of the choices shown to the player.

Choice is described in detail in it's own section, refere to that for further information.

Branch

Branch at first glance is very similar to Choice, but it is quite different. It has no txt, no npc. The branch fields only have a condition and target and no label. Unlike choice there is no maximum number of branches in a node and one can add as many as needed by pressing the '+New Branch' button.

Branch is described in detail in it's own section, refere to that for further information.

Jump

The set of fields for a jump node is almost identical to that of a branch node, with only the branch fields replaced with one eval_jump_to field.

Jump is described in detail in it's own section... You know the drill by now...

Plot graph

The plot graph takes up the majority of the editor window. Each plot node is represented by a small, colored rectangle. Arrows show how the nodes are connected. Each node has a small, round button (nub) next to its name, clickin it will select the node and load it into the node editor.

When a node is selected the editor highlights it's direct ancestor all it's descendants and fades out all the nodes that can no longer be reached from the selected node.

Depending on the content of a node, additional icons can be displayed under the nodes name. These help to find nodes with branches, commands, images, pc or npc. Hovering the mouse cursor over one of those icons usually give extra informations without the need to select the node and look through its fields.

dev/item_editor.html

This is a tool designed to edit and preview existing clothes. It can also be used to assign items to shop, but a more specialized tool for that also exists.

One might need to edit this tool to add/remove custom item tags suitable for each game.

dev/item_maker.html

This is a tool designed to create new clothing items from image files. It doesn't save the output to a file, but offers it in a text field so that it can be copy/pasted into data/items.txt

dev/shop_editor.html

This is a tool designed to edit the content of shops.

dev/mod_manager.html

This is a tool meant to be used by end users/players. It allows to load mods from .py files and determine in what order they are loaded by the game.

dev/make_datalist.py

This script generates datalists (hints) for plot_editor.html. Copy/paste the output.

dev/make_doc.py

This script generates rough API documentation in html format based on function docstrings.

dev/svg_gen.py

This script generates colored dots and arrows as used by the plot_editor.html. It is dummy stupid.

dev/webpy.py

Script to convert a dir of images(png/jpg) to .webp files, libwebp needs to be installed and present (on path).

Usage:
python webpy.py source_dir [target_dir] [cwebp_args]

Most of the engines code is organized into functions, classes are avoided, unless they can provide some useful features.

This is a deliberate design choice, that minimizes the amount of redundant typing -it's simpler, smaller, faster, better (?) to write music('oh_my') then for example game.audio.music('oh_my'). Those few extra letters might not seem much, but repeated thousands of times in the plot.txt file could add megabytes of bloat.

Some parts of the engine could be simplified or improved if some standard Python library modules where used, unfortunately importing these modules from Brython require the browser to download and process multiple megabytes of javascript - something that probably best be avoided.

All functions that start with an underscore (like _on_choice_click()) are 'private' functions, implementation details that most game authors needn't to worry about. One shouldn't use them from inside a cmd fields in a plot node.

Public API:

All functions: