Creating a Custom Screen Component in Monogatari VN Engine

Monogatari Visual Novel Engine

Introduction

Monogatari is a relatively new visual novel engine written in JavaScript. Not only does this give it the advantage of being relatively simple to pick up and work with (especially for non-developers), but it also allows it to be deployed directly to browser, through electron, or bound into a native application’s web view. While the engine contains most of the core features that you require for a simple game, such as dialogue and scenes, complex functionality will need to be extended through JavaScript. Custom screens, like an inventory or a map, will need to be created using custom components. In this guide, I will show you how to create, display, and close a custom screen using easily-extended components.

Note: I am currently using the nightly version of Monogatari [v2.0.0beta12]. This guide may not work with the stable branch (v.1.4.1 as of writing)

Creating a Custom Screen Component

Even though Monogatari currently contains several important screen components out of the box, you may find the need to create a custom one. Fortunately, Monogatari allows us to extend a built-in screen component and define a new one. First, we will be extending the default ScreenComponent. In this example, I will be naming the custom screen component CustomScreen, feel free to change the name to suit your project.

Within your script.js file (somewhere above monogatari.script), add the following to declare a new component:

class CustomScreen extends Monogatari.ScreenComponent{
	constructor(){
		super ();
	}

	render () {
		return `
			<h1>Comm Unit Here</h1>
			<p>Our custom screen has loaded!</p>
		`;
	}
}

Any HTML contained within the render function will be displayed when our component is shown. Now that we have a custom screen component, we need to define a tag for it and register it with the engine. The tag will be what we use to reference the screen component. Add the following lines directly below the class that you just declared:

CustomScreen.tag = 'custom-screen';

monogatari.registerComponent (CustomScreen);

Inserting Tag into HTML

Now that we have created a custom screen component and declared a tag for it, the next step is adding it to our HTML. An added screen component will have no quick menu at the bottom of the screen. It will also not contain a dialogue box. A good example of a screen component is a map that the user clicks to interact with. Use these screens to drive game-play forward through events.

To add a the screen component, you will need to add the tags directly within the <visual-novel> </visual-novel> tags contained within index.html. I added mine below the <help-screen> tags like this:

...
  <help-screen></help-screen>
  <custom-screen></custom-screen>	
</visual-novel>
...

Now, whenever we display our custom screen component, it will replace any component currently contained on the screen.

Opening/Closing Custom Screen Components

By now we have created our custom screen component and added it to index.html. We are currently missing a way to open and close the screens. There are two ways that we can do this, programmatically and by action. Let’s take a look at each method below.

Programmatically

By opening a screen programmatically, we can use our script to open the screen without user input. In order to do this, we need to make sure that we are able to reverse this option as well. In your script.js, somewhere below the custom component that we created, we need to add the following functions:

const openCustomScreen = {
  'Function':{
    'Apply': function () {
      	monogatari.element ().find ('[data-screen="custom-screen"]').show();

      return true;
    },
    'Reverse': function () {
      monogatari.element ().find ('[data-screen="custom-screen"]').hide();
    }   
	
  }
}

const closeCustomScreen = {
  'Function':{
    'Apply': function () {
      monogatari.element ().find ('[data-screen="custom-screen"]').hide();
      return true;
    },
    'Reverse': function () {
      monogatari.element ().find ('[data-screen="custom-screen"]').show();
    }   
	
  }
}

The two functions above are reversible functions. They will ‘undo’ their action when the user click the back button. The ‘Apply’ function is called whenever our script calls this function. All we are doing within the ‘Apply’ function is locating our <custom-screen> tag and setting its state to true or false. Reversing the function does the opposite.

In order to call our function, just add it within your monogatari.script object at the very bottom of script.js:

...
'Opening Custom Standalone Screen',

openCustomScreen,
...

To close it, you do the exact same but add closeCustomScreen to the script.

Action

Most of the time, you will want to open a standalone screen by user action. An example of this is a user clicking the map icon to open the map screen. This is done by calling the action open-screen:

...
buttons:[{
  string: 'Open Custom Screen',
    data: {
      action: 'open-screen',
      open: 'custom'
  }
},
{
  string: 'Close Custom Screen',
    data: {
      action: 'back',
  }
}]
...

Note: The open key should NOT contain the -screen on the end of it. Instead of custom-screen we are just using custom.

To close a screen, we just use the action back. This will automatically return you to the previously opened screen.

That’s it! By now you should have a custom screen component in Monogatari that you can open and close programmatically or by actions.