Visionaire is a really powerful engine designed originally for 2D point ‘n click adventure games and it’s among the best options if you plan to make such a game. It has been used in many successful commercial games, most notably by Daedalic Entertainment. You can see a comprehensive list of games made with this engine here. This guide will help newcomers to easily setup and build their first game, but is also a handy ref for experienced developers during the production of our game. Apart from our own studio’s experience with working with the engine, this guide practically contains consolidated and structured information and examples available in the following links:

https://wiki.visionaire-tracker.net (Wiki)
http://www.visionaire-studio.com/luadocs (API Reference)
https://www.visionaire-studio.net/forum (Forum)
https://discord.gg/feQkHgNe (Discord)

You have two options to download the engine and start playing around:

Test Version

You can download it from here. Its purpose is to test if the software fulfils your needs before buying a license. It is fully featured with the following limitations:

• Max 10 scenes.
• You cannot create builds.

Full Version

You can buy a license that suits your needs and download the latest version from here. You will then receive the registration details by email and you can activate your full version under Extras -> Register Editor.


Note: if for any reason the ‘Register editor’ is not showing, edit the Viseditor.ini and delete the line showing RegisteredVersion. You can go directly to the proper folder from here:

.ved  – The project file that holds all the data structure of your project in an XML format. You can also open and edit it with any text editor (only if you know what you are doing!).

.veb – A compressed version of the .ved file. It holds the exact same data but it has much less size. It is not viewable or editable.

You can choose which of the above formats your project file will be in at any time when saving:



.vis – The main output file of your compiled game. It holds all your game’s assets (graphics, sounds etc.)

Below you can see the minumum required steps to have a game up and running from a blank project, considering a 3rd person game. For more details in each step you can refer to the relevant section of this guide.

1. Add a Scene. The scene needs to have a background image and a way system.
2. Add Scene Objects for the character to interact with. Define their interaction polygons, give them a name and set the position for the character to walk to when interacting with them.
3. Add a Font for the text to be displayed in game.
4. Add the Playable Character and the relevant images. Set his starting position and the font to appear when he talks.
5. Add your Cursors and their active/inactive images. You can have the main game cursor, cursor for you actions (Look, Use etc). Set the animation center for each one.
6. Setup the Interface of the game. This includes all commands which represent specific actions and use the cursors we have defined above. Don’t forget to assign the interface to the playable character.
7. Setup game’s Properties. Set your game’s resolution, the first scene, the playable character.
8. Create Actions when interacting with Scene Objects.

If you have done the above you can run your game (CTRL+F9) and how it looks.  

Visionaire uses a config.ini file to predefine the settings of the started game. The config.ini is created automatically when you build your game and is placed in the same directory as the player. The default config.ini looks like this:

FILE = data.vis
# 
# FULLSCREEN = {yes|no}
# yes - starts the game in fullscreen
# no - starts the game in a window
FULLSCREEN = yes
# 
# RESOLUTION = {Auto|Desktop|Game}
# Auto - wide-screen support is activated if a wide-screen display is detected
# Desktop - current desktop resolution is used when game is started in full screen mode
# Game - game is initialized with the resolution specified in the game
RESOLUTION = desktop
# 
# INTRO = {yes|no}
# yes - Show the intro movie on start-up
# no - Don't show the intro movie
# 
# LANGUAGE = {German|English|...}
# 
# LOGLEVEL = {Info|Warning|Error}
LOGLEVEL = info

Visionaire checks the config.ini when it runs the game and adjust the settings accordingly; if you want to change any settings edit config.ini manually before starting the game.

Dynamic Configuration

For a released game with a proper settings screen you need to write and read from the config.ini dynamically from within the game. The script below will allow you to do that in a new config.ini file which will be located in the localAppDir of the user.

Tip: if for any reason you need to delete the config.ini file at some point you can do so with:

os.remove(localAppDir .. "/config.ini")

One of the first things you need to do is to set the resolution of your game through the game properties:


This will be the default resolution of your game, and normally it should match your graphics resolution. You can get the current resolution using getProperty(“display_resolution”) which returns the rectangle that is drawn in (excluding any black borders):

local resx = getProperty("display_resolution").width
local resy = getProperty("display_resolution").height

Using Values and Strings in Display Texts

• Integer values: <vi=valuename>
• String values: <vs=valuename>

Text Pauses

You can control how long a text will be displayed for by using <p> tags after the text as follows:

Wait until left mouse button is clicked to continue <p>
Continue after 2500 milliseconds (ms) <p2500ms> 
Continue after 2.5 seconds (s) <p2.5s> or <p2.5>
Wait until linked speech file has finished playing <pa>
Wait until linked speech file has finished playing (with fallback time (in ms) if media file is missing or corrupted <pa2500ms>
Automatic pause <pt> (character count * 130ms * VGameTextSpeed%)

Adjusting Text Speed

By default the display time of a text depends on the number of characters. Internally Visionaire waits for 130ms per char. So if the current text has 30 chars (including blanks, etc) it will display for 30 x 130 = 3900 ms. You can adjust this time as follows:

game.TextSpeed = 100 -- default value (in %), lowering it will slow text down.

Wait for Click to Skip Text

By implementing the textStarted event handler you have a faster way to make all your game’s text skippable only with a click and not depending on any display time:

function sText(text)

  if Conditions["manual_skip_text"].Value then -- create the 'manual_skip_text' condition somewhere in your game.
    text.TimeToWait = -1 -- this adjusts the total time (in msec) for showing current text. Setting this to -1 waits indefinitely for a click.
    text.WaitForAudio = false -- it ignored any linked audio file 
  end 

end 

registerEventHandler("textStarted", "sText") -- event handler for begin text

     

Query name of scene

Wrap in If lua action part:

return game.CurrentScene == Scenes["101_river"]

Check if the name of the scene contains specific string

Good for filtering scenes!

if string.match(game.CurrentScene:getName(), "minigame") then ... end

Check if a scene is a Menu

game.CurrentScene.SceneIsMenu

To add a new scene, from the top toolbar:


Choose ‘Scene’ and enter a name.

Add a background by accessing scene’s properties:

There are a couple of ways to change a scene, and they are quite straightforward using action parts.

1. Change to a new scene, relocate the character

Use the ‘Change scene’ action part. This will position the character to a specific object of another scene, align him as we need and change to this scene:



2. Change to a new scene of a specific character

We can change to a scene of any character we want using the ‘Change to scene of a character’ action part. Changing to current character can be useful also when returning to the game from a menu scene for example.



3. Show a scene or menu, without any character relocation

If we don’t need or want the character to be relocated at the time of scene change, we can just show a scene with the ‘Show scene/menu’ action part. We can relocate him manually later if we need. This action part can also show menus.



In all above action parts, you can define how the transition will be made:

• Immediately show scene/menu. This will change to the scene/menu without any transition effect.
• Fade to scene/menu. This will use a transition effect during the change.

For transition effects, the ‘Fade out and fade in’ effect is used by default. If we want a different effect, we can choose one using the ‘Set fade effect to new scene’ action part. We can also define the duration of the effect:



There is a variety of fade effects to choose from:

• Fade in
• Fade out
• Fade out and fade in
• Fade to new scene
• Shift left
• Shift right
• Tunnel effect

Especially for the tunnel effect, you can adjust how it looks with lua:

game.FadeCenter = {x=300,y=200} -- The position of the center of the circle when you fade out the scene
game.FadeInCenter = {x=600,y=700} -- The position of the center of the circle when you fade in the scene
game.FadeRadius = 200 -- You can have a nice blur effect around the circle center, define the radius here

Note: the change in the fade effect will remain until you change it again.

Way Systems tell the engine where the character is allowed to walk in the scene and how the scaling works as he moves around. To create a new way system for a scene:



You can assign a default way system to a scene through its properties.

Multiple Way Systems

You can use multiple way systems in a scene. This can useful in cases when you the way system of a system is modified, very common for example when doors open to reveal new areas. You can change the currently used way system with the relevant action part:



Each way system consists of way borders and way points, so let’s define them also.

Way borders

Way borders define the walkable area in the scene; any character cannot walk outside this area.

You define a way border by creating points; you’ll notice that your cursor will change to when you hover over the scene. Make sure you close the way border by moving the cursor over the first way point. Cursor will change to , click and you have your way border. Alternatively, you can close a way border by right clicking while you drag a way border point.