For an example, try the web demo: https://halfstar.itch.io/matchanovel

MatchaNovel is an open source multiplatform engine for narrative works, like visual novels and adventure games. It can be integrated with the Defold game engine or other Lua based engines, to use narrative features like a writer friendly scripting system and automatic textboxes in other genres as well.

It consists of these parts:

• MatchaScript: a Lua based scripting language for narrative works, that can be imported into an engine

• MatchaNovel: a Lua backend for visual novels that extends MatchaScript, and allows renpy-like scripting

• MatchaNovel for Defold: a library and GUI for the open source 2D+3D game engine Defold

• Jasmine: a textbox library for Defold

Currently working fully on these platforms: Windows, Linux, macOS, Android, iOS, HTML5

Platforms it can export to, but I could not test yet without a devkit: Nintendo Switch

• writer friendly scripting language
• you can make a full release with only MatchaScript code, or you can use Defold to edit the GUI and scenes in a WYSIWYG editor
• strong math and logic support by using Lua expressions and math libraries in the script, or import full Lua files as extensions
• Spine support
• FMOD support
• particle effects
• inbuilt pronoun system
• make your own syntax by changing the MatchaScript definitions
• can be used as dialogue system in a full Defold game, or use mini games made in Defold in your visual novel
• small build size: less than 5 MB, plus your assets

You can use MatchaNovel either:

• by opening the empty template project in Defold (recommended for releasing a visual novel)
• (There is also a seperate template that includes Japanese fonts, which are not in the English version to keep the file size down.)
• or by downloading the standalone reader and editing the script and asset files (recommended for quick prototyping without advanced features)
• or by importing the library in Defold or another Lua based engine (recommended for integrating into a larger non-VN game)

If you import the MatchaNovel library into an existing Defold project, you should also install the DefOS library, so that the fullscreen setting will work.

You can play a project by pressing Project -> Build (Ctrl+B) in Defold, or by starting matchanovel.exe in the reader project.

Your assets should be put into the folders in /assets. The most important is the script, which contains your text and logic.

Let's try our first script. Write this line in assets/scripts/script.txt:

That's enough for a hello world program. If you start the project, it will repeat the text you wrote in the script. This works because any text that is not recognized as another valid action will be used as "say" action, and printed to the textbox.

Now some more actions:

This defines the current line as the label called start. The label name can be any name valid as Lua variable, so it should start with a letter, and consist only of letters, numbers and underscores. The label start is a special label, this is where the script will start when starting a new game.

To jump to a label, use

If you want a text to be spoken by a specific character, use a colon:

The name before the colon will be displayed above the text. If you don't want to write out the full name every time, you can assign a character to a variable, like this:

Line breaks will be added automatically according to the size of the text and the box. You can also add manual line breaks by using \n.

If you want for example "jump" to be spoken, but not by a character, you can't just write

as that's a keyword already. But you could write

to explicitly let it be a say command, but without a speaker.

In general, the line

will set the variable named x to z, and

will set the property y of the object x to z.

Variables can also be used directly in text, by putting them in curly brackets:

If you need a string capitalized, just write the name capitalized when calling it.

will be displayed as:

Alice: test Test TEST.

You can use Lua expessions to set a variable:

You can even use Lua expressions in curly brackets:

Additionally there are some operators that MatchNovel has that are not part of standard Lua:

Note that unlike similar operators in other languages, these will also work if the first variable is not yet defined. Using a += 2 when a == nil, will result in a being treated as being 0, so after the operator it will end up with a = 2. So if you want to create a flag and set it to true, using flag++ is functionally the same as flag = true, although slightly less efficent, using a number instead of a boolean.

Also note that a++ is a whole action taking its own line, and can not be used inside other expressions, and does not have variations. There is NO a = b++, or ++a, or a--, or --a, as these would clash with standard Lua syntax. It's a shortcut to increase a variable by one, and that's all.

To show a sprite for a character, use

where a.sprite must be either a file in /assets/images/sprites, or the path from your project folder to the file, like

Note that any folder outside of /assets that you use this way must be added to Custom Resources in your game.project file.

If you don't specify a position, the character will be automatically positioned, see section Automatic sprite positioning.

To define a position, define a variable with properties x and y:

The units of x and y are fractions of the screen size. So the position x=0 is at the left of the screen, x=1 at the right, x=0.5 at the center, and x=0.75 between center and right. y=0 is the bottom, y=1 the top, and so on. You can also use numbers smaller than 0 or larger than 1, so for example y=-0.5 would start a half screen height below the bottom.

You can even set a scale to a position. Sprites that are shown on that position will be scaled with the factor of that position. So a character with scale 1.2 on a position with scale 0.5 will be shown with a scale of 0.6.

If you don't want a character to appear instantly, you can also use transitions, like

where transition is the name of the transition you would like to use, and duration the time the transition will use in seconds. If no duration is given, the default value will be used.

By default, a new character will be shown in front of all previous characters. You can also specify to shown them in front of a certain character, below a character, at the back, or at the front:

You can also change the default arguments for show. If you want all characters to fade in with a duration of 1.2 seconds and added to the back instead of the front, as long as no other values are used, you can do this:

To hide a character again, use:

You can also hide all characters at once:

You can again use transitions for this, or the value to to give a vector to move in, like:

You can also move a shown sprite to a new position:

Like with show, you can also move a character above or below another character (or the front, or the back). You don't have to specify a to value, without it the sprite will stay in place, and just change the order.

For movement animations, you can also change the easing:

The default easing if none is specified is INOUTSINE. There are the following easing types: LINEAR, INBACK, EASING_OUTBACK, INOUTBACK, OUTINBACK, INBOUNCE, OUTBOUNCE, INOUTBOUNCE, OUTINBOUNCE, INELASTIC, OUTELASTIC, INOUTELASTIC, OUTINELASTIC, INSINE, OUTSINE, INOUTSINE, OUTINSINE, INEXPO, OUTEXPO, INOUTEXPO, OUTINEXPO, INCIRC, OUTCIRC, INOUTCIRC, OUTINCIRC, INQUAD, OUTQUAD, INOUTQUAD, OUTINQUAD, INCUBIC, OUTCUBIC, INOUTCUBIC, OUTINCUBIC, INQUART, OUTQUART, INOUTQUART, OUTINQUART, INQUINT, OUTQUINT, INOUTQUINT, OUTINQUINT. For details on how those easings work, see the MatchaNovel demo, or the Defold manual.

You can flip a sprite horizontally with the flip action. By default, it will show a rotation on the z axis with a duration of 1 second, but you can also change the duration.

If instead of a flip animation, you want to show a sprite flipped in the first place, you set the values flip_x or flip_y directly before showing it.

You can change at which position a new sprite without a position will be placed. By default, they will be put at the highest number, so if there are 3 automatically positioned sprites already, the new one will be placed at position 4. If you want it at another position, use a number as position argument. For example, if you want the fourth new sprite to be put at position 3, and the old 3 at 4, use:

You can customize the rules for automatic sprite positioning.

To set the width of screen that the sprites are spread on, use sprites.auto_n.width, with n being the total number of sprites, and the width 1.0 being the whole width of the screen.

You can also set the positions individually using sprites.auto_i_n, with n being the total number of sprites, and i the number of the individual sprite.

The duration of the automatic ordering of sprites if set by the variable sprites.auto.duration:

To change the image of a shown character, you can just change its sprite variable. This will change the sprite immediately and permanently.

To make changing sprites easier, the expression system exists. You can manually define expressions with different sprites.

If you now call that expression with alice.sad, the character alice will change its expression to sad, which means it will change its sprite to alice_sad.png.

If an expression is used in its own line, it will stay until changed again. You can also use an expression on the speaker of a "say" line. In this case, the sprite will change as well, but only for this one line. So the next line it will revert again.

The pattern of the filename in the example above, charactername_expressionname.png, will be used by default if you call an expression that you have not defined. So even without a manual definition, you can just use

as long as the file /assets/images/sprites/alice_angry.png exists.

To show a background scene, either use a filename:

or a scene name:

The scene name follows similar rules as sprites, but with the default folder for filenames without a path being /assets/images/background.

You can again use the same syntax for transitions and their duration:

You can also change the default transition and duration, so you don't have to change it to the same values every time.

A new argument is color, which can be used to change the tint of the image.

This will tint the image red. For colors you can either use HTML names, hex colors, or variables with RGB values (from 0 to 1). These will all do the same:

You can also use a color instead of an image file to create a solid color background, like

Furthermore, you can use the argument transition_color to change the color of a transition (if it has any), like:

You can add branches based on the value of a variable, with if, else, and elseif: