monogatari / monogatari

Monogatari is a simple web visual novel engine, created to bring Visual Novels to the web.

Monogatari

Built to bring Visual Novels to the modern web and take them to the next level, making it easy for anyone to create and distribute Visual Novels in a simple way so that anyone can enjoy them on pretty much anywhere, create games with features that no one has ever imagined... It is time for Visual Novels to evolve.

Website: https://monogatari.io/

Demo: https://monogatari.io/demo/

Discord: https://discord.gg/gWSeDTz

Twitter: https://twitter.com/monogatari

Community: https://community.monogatari.io/

Features

• Responsive out of the box
• Plays nice with Electron for Desktop apps and Cordova for mobile apps
• Simple Syntax
• Progressive Web App Features allowing offline game play
• Allows you to use any kind of media supported by browsers
• Compatible with all major browsers
• Includes libraries for animations and particle effects
• Allows saving/loading games
• Extensible, you just can't imagine how much!

What do I need to get Started?

The first thing about Monogatari that you should probably know is that with it, your visual novel is a web page first and a game later. That means that Monogatari has been created specifically for the web, putting things like responsiveness (the fact that your game will adapt to any screen or device size) first. You don't necessarily need to think of your game this way as well, but you'll certainly take the most out of Monogatari if you do.

Set up your environment

To develop in Monogatari you would need the same as to develop a webpage, you just need a text editor capable of editing HTML, Javascript and CSS, which means that pretty much any text editor should work, even Windows NotePad but to make it easier, you probably want one with code syntax highlighting.

Some recommended (and free) ones include:

• Visual Studio Code
• Atom
• Brackets

Take a look at them and pick the one you like the most and feel comfortable with, this will be your main tool from now on.

Now, you can always open a website by just clicking the file index.html and opening it with your browser, however there are small aspects of Monogatari that work better when served through a web server. You don't need anything fancy for this, in fact there's a perfectly fine web server you can download from the Chrome Store

As previously mentioned, the use of a web server is completely optional, you can just open your game with the browser as a file and it will run just fine, the web server will allow you to test features such as the Service Workers, needed for Monogatari's offline support and asset preloading.

Workflow

Ok so now you have the environment set up, you have some idea on what the files you got are for so how can you start developing your game?

1. Try the game first, open the index.html file inside the directory you just unzipped and play the sample game through.
2. Once you've played it once, open the directory (the one you unzipped) with the editor you chose to start making changes.
3. Open the script.js file with your editor, find the variable called script, as you'll see, all the dialogs you just saw are just a simple list in there. More information can be found in the documentation.
4. Change one of the dialogs, save the file and reload the game (just like you reload a website).
5. Play it again and you'll see the dialog changed just like you made it.
6. Now try adding more dialog to it and you'll quickly get how things are done.
7. Once you've gotten yourself used to adding dialogs, add a scene as a challenge, that means you'll have to add your image file to the img/scenes/ directory , more instructions are on the link.

If you manage to do all that, congratulations! You just made your first game and are probably more familiarized with the workflow you'll be using, just make changes, save, reload, try and repeat!

Documentation

You can take a look at the documentation in https://developers.monogatari.io/

You can also contribute to it in the Documentation repository

Monogatari as a Module

Monogatari's core functionality is also released as an UMD module, therefore it's possible to use it either on a browser as a global library, using ES6 modules or Node.js modules.

Browser

<script src='./monogatari.js'></script>

const monogatari = Monogatari.default;

ES6 Modules

import Monogatari from '@monogatari/core';

Node.JS

const Monogatari = require ('@monogatari/core');

Contributing

Contributions are always welcome! Read the CONTRIBUTING file to get started.

License

Monogatari is a Free Open Source Software project released under the MIT License.

monogatari's Issues

Debug in the browser

How do you debug the engine in the browser? Looks like neither Chrome not Firefox cannot load the source maps.

Chrome

Just writes Source map detected and nothing more. I can't see it or anything.

Firefox

Error code card: TypeError: NetworkError when attempting to fetch resource.
Resource URL: file:///<path>/dist/engine/monogatari.js
Code Card URL: /monogatari.map

---

I doing something wrong?

Add Cordova Support

Monogatari is currently able to run on PhoneGap, however there is no documentation and there are some elements missing that even if not required should be added.

Add missing translations

Some new strings have been added to the UI translations

"AutoPlay": "Auto",
"Hide": "Hide",
"Show": "Show",
"SlotDeletion": "Are you sure you want to delete this slot?",
"SlotOverwrite": "Are you sure you want to overwrite this slot?",
"Stop": "Stop",

I have updated Spanish and English languages but some languages are missing those translations, I was wondering if you guys could help @BakaKiller, @ign1ght (Only if you got some free time of course) :)

After that, only Japanese would be missing but that one still needs a general check since it has been mostly google translated.

Idea - improved choices

Hello everyone.

When I started to deal with "choices", I found out that you can only change variables like storage.player.name before or after "choices".

I would like there to be another criteria for "choices".

For example:
{"Choice": {
----"Dialog": "Some text...",
----"Option#1": {
--------"Text": "Some text #2 ...",
--------"Do": "e.g. jump ..."
--------"Save": storage.player.name = "KazutoSensei"
----},
----// [...]
}}

Why?
It's hard to find everything when the game gets bigger and if every storage-saving get separated from his action/choice it will get harder and difficould to read. (And I know CTRL + F e.g. 😄 )

Greetings

how I want a gui tool for this novel engine

....

Height and Width Parameter for Show Command

Feature Suggestion: Adding a Height/Width parameter for the show command for both characters and images.

Add auto play feature

An auto play option needs to be implemented, it should go through the dialogs without needing user interaction and stopping on choices and other elements that do require user input.

A timeout calling next or analyseStatement is probably the best way to go but the time will have to be determined by the text length, and probably also related to the text speed.

Hide all elements on game end.

Some elements like the centered text stay in the game screen after it ends, causing them to appear when start is pressed again.

Conditions

hey.
I read about the possibility of conditions for choices. But I can't find how its possible to define a variable for the condition.
So, the docs example:
"Player":{ "Text": "I'm a Player.", "Do": "Player", "Condition": "played == true" // This will only be shown if the condition is true. }
Where is played = true defined?

thank you!

Add a way to request/input data from the player

Currently, a way to do this is to use a prompt inside a function statement:

"This is an example",
function(){
    var new_name = null;
    do{
        new_name = prompt("My name is...");

    }while(new_name == null);

    characters["YourCharacter"]["Name"] = new_name;
},
"Now you have a name"

However, this will not work in electron since the use of blocking javascript like prompt is not permited, there should be a modal and a new statement to ask for input. "input My name is... | new_name" where the first part is the text that will be shown in the modal and new_name the variable to save it to is an option, however the use of a separator like "|" is not ideal, and there should also be a way to validate or add some constrictions to what the user can input.

Make the "jump" statement reversible

Right now, there's no way to go back from a "jump" statement, mainly due to technical complications but a solution could be to save a history stating the Label and Step where the jump originated and then, when going back, simply pop the last one and jump to that label and step.

The problem here is that this may be troublesome on some scripts, for example:

"Start": [
    "stop music",
    "jump OtherLabel"
],

"OtherLabel": [
    "scene someScene",
    "..."
]

So, once the jump is run, an object like this one would be saved:

{
    label: "Start",
    step: 1
}

If the player goes back, that object would be retrieved and a jump to that label and step (-1) would be made, however, the step - 1 position is a "stop" statement and since it will be run, it will automatically run the "jump" statement again rendering the back unusable again.

If other statement that doesn't cause the automatic execution of the next one such as a dialog is used, then it would work just fine since it would give the player the opportunity to keep backing up.

"Start": [
    "Some dialog",
    "jump OtherLabel"
],

"OtherLabel": [
    "scene someScene",
    "..."
]

Add a new screen and functionality for auto saves.

Add:

• A screen specially for loading auto saved games based
• A way to navigate through this screen and the load one
• An option in the engine to define the time interval between auto saves

Can the Monogatari Syntax Be Improved?

Right now, it looks like the "display" statement is just used for the messages, the code also supports displaying images but that seems to be duplicate functions from the ones found in the "show" statement, maybe display is not needed at all.

For example, right now it seems that these two statements are completely the same:

"show image.png with fadeIn",
"display image.png with fadeIn"
``

service-worker.js at null

Hello !
First your work is AWESOME ! 🥇

I have a little bug

I have the file with index.html I try to copy to folder js but is same.

I'm on the fact being a trifle, the more I do not know where its come from > _ <

Can you help me ?

Other little things on your doc :
https://monogatari.io/documentation/script/scenes/

its "scenes" not "scene" I do not understand why it does not work after my copy paste ^^

Can the app be embedded in a page?

Can a Monogatari game be embedded as part of a web page, rather than take up a full page to itself?

If you want to know why I'm asking, read on. If not, you can stop reading now. ;-)

I'm studying a masters in Serious Games and work for the LearnGaelic.scot website.

I'm currently considering building my dissertation project around Monogatari -- my draft title is Repurposing an open source game engine for the delivery of online language learning content or something similar.

Basically, the idea is to write a front end wrapper that allows teachers to produce dialogues and stories, as well as interactive quizzes, then generates the Monogatari script (with some embedded custom javascript to handle communication with a host virtual learning environment).

Why?

Well, tools for the teaching industry tend to suffer either from being part of closed platforms (normally tied to specific webservices) or from lack of updates and a slow degradation of compatibility (Hot Potatoes, long the most popular free tool, generates some activities that won't work on iOS and others that render wrong in Firefox).

By wrapping the Monogatari engine, most of the compatibility issues are delegated to the game engine, so there's a much lower maintenance requirement -- any compatibility changes in Monogatari can automatically be incorporated into my output; only changes to the script format will necessitate updating the codebase.

So... all that said, the reason I'm asking about embedding in a page is that my first use case (dialogues) are intended to replace things like this with something more dynamic and engaging, and for our uses (and many other educators') it would be very handy to present the output of Monogatari in this way.

Add equivalent configuration from the .htaccess file to a NGINX configuration file.

We currently provide an .htaccess file, mainly to enable the custom error pages provided but also to make the index handle all requests. Right now Monogatari doesn't really handle anything but in the future it may.

We need to add an equivalent NGINX configuration, at least the closest possible.

Change Release Flow

Given the adoption of more and more ES6 specific elements and functions, the release flow must be changed in order to add a parser like the Closure Compiler that transforms all the code to ES5 code and thus prevents compatibility issues with older versions of browsers and OS such as the one in #36

Add a way to start the game right away.

Currently you have to go through the main menu to start the game, there should be an option to start the game right away without showing the main menu.

Improve HTML handling API

Handling the whole HTML from the engine JS has solved one core issue in Monogatari, updating the engine for a work in progress game is now as simple as replacing 3 files but I believe it has also made it more difficult for casual developers to simply modify the HTML structure.

To make it easier, we need to make it really simple to modify the HTML via JS APIs in the engine and with a really awesome documentation

Preload images

Since images of characters and backgrounds are served through the internet it takes a while, so player will see rather ugly process of sequential pictures loading.

It would be much better to preload all needed images e.g. right after each jump, maybe even with beautiful progress bar. Of course you can do it manually with something like

"Label": [
  function() {
    new Image("path/to/image.jpg");
    new Image("path/to/image2.png");    
  },
  // ...
]

but having special support in the engine is nicer.

Choice Object does not work right after a jump

When having something like this, the choice dialog at the Yes label is not shown but the dialog inside it is.

var script = {

    // The game starts here.

    "Start": [      

        {

            "Choice": {

                "Dialog": "h Have you already read some documentation?",

                "Yes": {

                    "Text": "Yes",

                    "Do": "jump Yes"

                },

                "No": {

                    "Text": "No",

                    "Do": "jump No"

                }

            }

        }

    ],

 

    "Yes": [{

            "Choice": {

                "Dialog": "h show dialog",

                "Yes": {

                    "Text": "Yes",

                    "Do": "jump Yes"

                },

                "No": {

                    "Text": "No",

                    "Do": "jump No"

                }

            }

        },

        "h That's awesome!",

        "h Then you are ready to go ahead and create an amazing Game!",

        "h I can't wait to see what story you'll tell!",

        "end"

    ],

 

    "No": [

 

        "h You can do it now.",

 

        "display message Help",

 

        "h Go ahead and create an amazing Game!",

        "h I can't wait to see what story you'll tell!",

        "end"

    ]

}

Replace jQuery for Aegis JS in Monogatari's core.

Updating script.js requires 2 refreshes to update

I'm using a local XAMPP server.

I've noticed that when I update script.js and refresh the local Monogatori web page, updates aren't applied on the first refresh. It seems I need to refresh twice. I have caching disabled and don't have this issue on other pages.

Is the script cached somewhere by the engine itself? My guess is that if so, the cached version is pulled rather than the updated version, resulting in the issue.

It is also possible my local server is messing with me.

Handle better changes to properties inside the options.js file

When the engine adds or changes a property in the settings or engine objects, some saved games may become invalid. Monogatari should handle those events in a graceful manner.

Fails to handle Image URLs with spaces

At least for the images sub object in the character definitions.

// Define the Characters
var characters = {
    "h":{
        "Name": "Hikaru",
        "Color": "#5bcaff"
    },
    "m": {
        "Name": "Marie Anne",
        "Color": "#220044",
        "Directory": "MUG",
        "Images":{
            "Normal": "Ayame Smile.png",
            "Annoyed": "Ayame Angry.png",
            "Mad": "Ayame Errkk.png",
            "Serious": "Ayame Lecture.png",
            "Surprise": "Ayame Surprised.png",
            "Sad": "Ayame Sad.png",
            "Happy": "Ayame Happy.png"
        }
    }
}

Chrome Dev Tools Network monitor shows it to be requesting
http://localhost:8080/atnConcept/img/characters/MUG/Ayame instead of http://localhost:8080/atnConcept/img/characters/MUG/Ayame Smile.png

Text appear animation

Haven't found that in the docs. Is it possible to have animation for the text when it appears on the screen? Like in this example: https://webstoryengine.org/

[suggestion/request] ink language integration with monogatari

so there's a choice-based language with some scripting potential, ink. it has a javascript version. it's open source!

i've found ink to be really pleasant to work with for writing CYOA stories, and i think it'd be neat to see it integrated into monogatari, as an alternative for the ren'py-like scripting language (which i like less, tbh).

Bug: H hotkey is not working

Don't forget about this :)

Not possible to localise characters' names?

As a workaround I can create multiple copies of each character, but thought I'd mention it in case it hasn't come up already. :)

More hotkeys for quick buttons

I was want to create a PR with more hotkeys for quick buttons, but in order to avoid situation like this i decided to ask several questions.

Current list of hotkeys (seems):

• Back - Left Arrow
• Next - Space or Right Arrow
• Settings - Esc
• Hide - H

Will be added list of hotkeys:

• Auto - A
• Save - S
• Load - L
• Quit - Q

So, questions:

1. Why do you create another events instead of simulate click?
   For example this:

// H Key
case 72:
    if ($_(`${selector} [data-action="distraction-free"]`).hasClass ('fa-eye')) {
        $_(`${selector} [data-action="distraction-free"]`).removeClass ('fa-eye');
        $_(`${selector} [data-action="distraction-free"]`).addClass ('fa-eye-slash');
        $_(`${selector} [data-ui="text"]`).hide ();
        Monogatari.global ('distraction-free', true);
    } else if ($_(`${selector} [data-action="distraction-free"]`).hasClass ('fa-eye-slash')) {
        $_(`${selector} [data-action="distraction-free"]`).removeClass ('fa-eye-slash');
        $_(`${selector} [data-action="distraction-free"]`).addClass ('fa-eye');
        $_(`${selector} [data-ui="text"]`).show ();
        Monogatari.global ('distraction-free', false);
    }
    break;

can be changed to this:

// H Key
case 72:
    button.click();
    break;

So, all the main logic can be placed in the one place instead of kinda copy in various places. I understand that this is architecture question and custom event can perform operations that doesn't related to the main event, but looks like in this situation in can be easily replaced.

2. I should use selectors like this ${selector} [data-*] in a pair with Aegis, yes? document.querySelector and something like this is not allowed?

Omit of the package-lock.json

Any reasons you add the package-lock.json in the .gitignore?
According to this you have to upload it.

[suggestion/request] Buttons

Hey!

Just thought that it would be great if you would add the possibility to use buttons in script to open messages or jump to a label.
maybe define the picture at the begin of the script and use it like a condition?

{"Button": {
    "Button": button1;
    },
    "True": "display message Inventory",
}},

would be great for using message based inventory systems or mailboxes, or a movement system with arrows.

for now, does someone know an easy workaround?

thank you!

Improve the Help Screen

Currently, the help provided is really minimal, there should be more information available, keyboard shortcuts should be added as well and maybe a better design is needed.

Add more languages

Currently Monogatari has only an English and Spanish translations, it would be nice to add more like:

• French
• Japanese
• Russian
• Chinese

Pass callback to function statement / accept Promise return value

It's useful when you want to do some asynchronous task (e.g. network request), next statement shouldn't be executed until the callback fires or Promise is resolved.

Also, I think you should't call next from analyzeStatement because it will call analyzeStatement again and it might result in stack overflow. Something like setTimeout(fn) is better.

Updating the engine on a work in progress isn't a smooth process

I suggest adding a .gitattributes with some merge driver lines so that
script.js index.html main.css main.js options.js
are excluded from merge, and maybe adding a "how to" in the readme/docs on updating the engine.

And perhaps a bit about gulp and the addons you're using too.

No sound in the demo

I have just downloaded the latest version of Monotagari. I am playing the demo and there's no sound (I know there should be some sound because in the multimedia section of the presentation the character says at a certain point "Unless you have your computer muted, you should be hearing music").

Sound is working fine in my computer, and browser is playing sound perfectly from other sources, like youtube for example.
Tried refreshing, did not work.
Checked Monogatari settings, volume is set to max.

Windows 10.
Firefox

Auto Save Slots are not Deletable

Right now, the deletion is using the SaveLabel to target the slot to delete which of course won't allow slots using the AutoSaveLabel to be deleted. There must be a way to identify the kind of slot to delete and use the proper label.

Functions don't use the actual value of storage variables.

I have this function in my game:

function percent_agi(a,b){return storage.prob100 = a/b*100;}

if i execute the function in the script like this:
percent_agi(storage.c_agi, 35),

it doesn't take the actual value of storage.c_agi. It takes always the start value which stands in the script.

Our game does not work on iOS9

Hello,

we used Monogatari.io in a student project for a serious game prototype to be used in a museum exhibition. Everything works fine, but for whatever reason the Safari browser on iOS 9 does not load and display the game.

I see it access some assets on the apache2 log, but the screen stays empty.

You can test our game here: 52.28.148.239

It works fine on all other mobile and desktop browsers (incl. an iPhone 6 with newer OS) and we are stumped.

Greetings,

Magnus

More information about Aegis Libraries shoul be available

Monogatari works internally with both Artemis and Kayros, however there is no information about them and thus no way for anyone to take advantage of them.

Artemis is pretty much a replacement for jQuery so Monogatari could ditch jQuery from the releases and also provides a lot of other functions that could be useful for anyone.

Kayros provides a CSS framework so people could take advantage of its grid and simple components.

Menu Music Overlaps

If I set the MenuMusic field in options, when the game is started the music doesn't stop and overlaps with any music in the game.

playAmbient gets called after start, which doesn't nessesarily toggle it off.
I'd put a PR for a stopAmbient function, but I'm not sure if this is how you intended it to be.

Ending from within script not quite working.

For some reason ending from the script doesn't quite work correctly, but ending via the data-action="end" button works normally.

What happens is that the music doesn't begin playing on an inscript end, thus there'd be no music on the menu and after hitting play again.

And neither method of ending clears the last scene, you can see this on a second run if a game initially starts without a scene.

Add a storage variable that persists in the saves.

Using varialbes in script.js

Sry, I'm pretty sure this is the wrong place to ask. But how do I define and use variables? For example after a choice. I've tried it with the normal js commands but it doesn't seem to work (game stays blank after it)

thank you!

[Discuss if worth doing] Splashscreen before main menu

With the understanding that contents can be displayed before showing the main menu by modifying the main menu element inside index.html, I wonder if we could have a more user-friendly way of implementation in future development.
For example, a specific label that, if defined, shows its content (image, text, media files etc.) before main menu (like the splashscreen label in Ren'Py)

Skip and Text Log

We need a skip function. Reader clicks on skip button to make the text fast-foward and click skip again to stop.
We also need a Text log for reader to keep track of story event if they forget previous text.

These two are essential for a Visual Novel.

I see that you are working on develop branch. I want to take time making a pull request but it would be kind of waste if you are gonna release a major update.

Is v2 ready to run for sample?

Improve support for custom positioning

Right now the positioning of elements such as images, choices, buttons etc is somewhat limited, this is mainly due to the whole responsiveness first ideal but finding a way to enable more custom positions while maintaining the responsiveness must be found.

Someone has proposed adding a "Position" property to the "Choice" objects like this:

{
    "Choice": {
    "dialog": "This will be displayed along with the choice!",
        "exit": {
            "Text": "Exit outside",
			"Position":"top:300px;left:700px;",
            "Do": "jump outside"
        },

        "kitchen": {
            "Text": "Go to kitchen",
            "Do": "jump kitchen"

        }
    }
}

Of course another unit other than pixels must be used but this is a pretty good idea.

Add support for LiveComposite character sprites

Would it be possible to composite character sprites out of components such as base.png, clothes.png, expression.png as in Ren'Py?

image eileen composite = Composite(
    (300, 600),
    (0, 0), "body.png",
    (0, 0), "clothes.png",
    (50, 50), "expression.png")

This feature would also be awesome for creating blinking sprites!

Voice files will not preload

On line 793 of js/monogatari.js:

	preloadPromises.push(preloadAudio("audio/music/voice" + voice[i]));

This seems to be a typo in the file path. I am making a VN with Monogatari, so I have fixed this for my VN this way:

-	preloadPromises.push(preloadAudio("audio/music/voice" + voice[i]));
+	preloadPromises.push(preloadAudio("audio/voice/" + voice[i]));