Visual Novel Engine for HTML5 Canvas

HTML

This is not going to be a HTML tutorial, so let's dive in. Quick!

Start with a minimal HTML5 template (if you're not so familiar with HTML; otherwise, skip ahead). Or begin with vntemplate.html and modify accordingly.

  
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Game Title</title>
    <meta name="description" content="Description of the game." />
    <link rel="stylesheet" href="style.css" />
    <script src="script/lib/require.js"></script>
  </head>
  <body>
    <!-- page content -->
  </body>
</html>

Modify the game title and description as necessary. Modify also the stylesheet or just remove the stylesheet line if you're going to be using default styles. If using 'form', stylesheets are necessary to layout the form.

Now add a canvas element in the page content (between body and /body tags). This one adds a default size canvas named "stage" centered on the browser. Modify the name to your preference.

  
    <div style="text-align: center;">
      <canvas id="stage" style="border:1px solid black" oncontextmenu="return false;" onselectstart="return false;">
        Your browser does not appear to support HTML5.  Try upgrading your browser to the latest version.<br/>
      </canvas>
    </div>

Below it, let's add the scripts. Starting with v.0.5.0, the engine and story script are loaded a bit differently and uses requireJS. You don't need to be familiar with requireJS but a little knowledge will help. For our purposes, just add a single script call to our HTML file.
```
  
    <script data-main="script/init.js" src="script/lib/require.js"></script>
								
```

The init.js file (or whatever you want to call it, e.g. game.js) includes all the necessary scripts and engine initialization we need. More on it below.

That's it for the HTML file. Moving on to other matters...

Initialization

The initialization script (as called from our requireJS line) includes our library paths, engine modules to load and stage initialization. The general structure of the init file is as below.
```
  
requirejs.config({
    // set library paths here
});

requirejs([
    // load modules here
],
 
function () {
    // initialization code goes here
});								
```

  
requirejs.config({
    baseUrl: 'script/lib',
    paths: {
        app: '../app',
        game: '../game'
    }
});

On the next section, we load our table of contents (TOC), our game engine, and other scripts. Starting with v.0.5.0, the engine is subdivided into modules. This makes it possible to load only those modules you will be using, thus speeding up load times and reducing memory footprint. Typically, you'd be needing all, but maybe you're making a game that does not need forms or checkpoints, for example. Just comment out or remove those modules you will not be using.

  
requirejs([
    // load TOC here
    "game/vntoc",
    // load canvas text
    "app/canvastext-0.4.1.mod",	
    // load base engine
    "app/vncanvas-base",
    // load (optional) engine modules
    "app/vncanvas-cmds",
	"app/vncanvas-media",
	"app/vncanvas-form",
	"app/vncanvas-cform",
	"app/vncanvas-bgnd",
	"app/vncanvas-actor",
	"app/vncanvas-atmo",
	"app/vncanvas-script",
    "app/vncanvas-chkpt",
    // place config, plugin, macro, etc. files here
    "game/vnconfig",
    "game/vnplugins"
],

A global configuration file is supported for setting game options, styling and themes. By putting most configurable options and styling here, the script files are much cleaner. Other files such as plugins, macros, etc. may also be added here.

Note the above example assumes the game engine is at folder app by default, and the game files are at folder game, as described in requirejs.config.

Note likewise that the .js extension of the files are not needed and will be added automatically.

Finally, to initialize our stage after all the modules have been loaded, add the script calls below. This used to be in the window.onLoad() function in the previous versions.
```
  
function () {
    Stage.Init("stage", 720, 480);
    Stage.script.Init("CHAPNAME");
});								
```

In the above example, Stage.Init() tells the engine to look for the canvas named "stage" (the one we named earlier) and informs it that the canvas is 720-by-480. Stage.script.Init() informs the engine of the story starting point (which is "CHAPNAME"). Note the "quotes" on the starting point; more on this later.

Also, prior to v.0.5.0, all scripts are loaded in memory, regardless whether it will be used or not during game play. Starting with this version, only the current chapter script is loaded, thereby reducing the memory footprint. Hence if you have a acript consisting of a number of chapters, only the current chapter is loaded in memory, with finished and/or future chapters not hogging precious memory space.

If you have a long story to tell, you'd normally want to split it into chapters or acts or even books. The TOC file you specified earlier tells the engine where to look for these chapters. (Note: the TOC keyword is required by the engine and should not be modified.)
```
  
TOC = [
    // place contents here
];								
```

In the sample below, I have 5 chapters that I added into the table. Note that the filename should now match the chapter label, and the .js extension removed.
```
  
TOC = [
    "game/prelude",
    "game/chapter1",
    "game/chapter2",
    "game/chapter3",
    "game/chapter4"
];								
```

Script

Alright, time to get to writing the story script (not to be confused with javascript). The structure is similar to TOC, except that it's a bit more complex than adding filenames. First, assign a title to it (something descriptive of course for your sake). Say we want to name it chapter1.
```
  
chapter1 = [
	// place contents here
];								
```

Now to add items to the script, we use the keyword-value pairs which tells the engine what to display, show, or whatever action the keyword defines.
```
  
chapter1 = [
	keyword1, param1,
	keyword2, param2,
	keyword3, param3,
	...
];								
```

For example, the following displays a background image and plays a background music.

  
chapter1 = [
	label, "chapter1",
	scene, {image:"background_image.jpg"},
	audio, {bgm:"background_music"},
	...
];

It is highly recommended that the first keyword-value pair in any script sequence is a label identifying the script sequence. If local saving is required, this is a requirement. The label should be equivalent to the script name. In this case, it is "chapter1".

Now all we have to do is to save this to a file (i.e. chapter1.js, in accordance to the requirement for v.0.5.0), then make sure to add it to the TOC. The TOC doesn't have to be in chapter order, but it would be good practice to keep things organized.

Lastly, remember Stage.script.Init() in init.js where we specify the entry point of the story? If we want chapter1 to be the entry point, we set it as the argument of Stage.script.Init(). Note, the quotes (as compared to previous versions). This is because the scripts are now loaded on demand, so we need to pass it as reference. If that's a bit confusing, think of it that during initialization, there is no script loaded yet, so we're just giving our engine the name of the script and it'll automatically look for the script.
```
  
function () {
    Stage.Init("stage", 720, 480);
    Stage.script.Init("chapter1");
});								
```

Customization (Optional)

Every game is unique. Oftentimes, you'd need functionalities not present in the core engine. Or a modification of a standard method. You can do this thru macros plug-ins or modpacks.

To keep your main script clean, it is recommended that you put all macros, plug-ins and modpacks on a separate file. Then add this to init.js after the engine modules, see also previous example.
```
  
requirejs([
    ...
    // place config, plugin, macro, etc. files here
    "game/vnconfig",
    "game/vnplugins"
],								
```

Reference

For reference, the structure of vn-CANVAS is illustrated in the PDF file given below.
```
  
VN-Canvas Structure - updated as of v.0.2.3+.
								
```