User Tools

Site Tools


quickstart

There were many changes to the engine and I'm only starting to rewrite this documentation

Quickstart Tutorial

Project installation

To create a new Annwvyn project, simply locate your Annwvyn installation and open the “Annwvyn” folder. Copy the “template” folder and paste it somewhere convinient, open the CMakeList file, change the “project name” on top of the file. Use CMake to generate a Visual Studio solution and open it.

Engine presentation

The strictly minimal code for your Annwvyn application is :

#include <Annwvyn.h>
 
using namespace Annwvyn; 
AnnMain()
{
	//Initialize the engine
	AnnInit("NameOfGame");
 
	//Start the main program loop. Loop will break if engine get signal to quit
	AnnGetEngine()->startGameplayLoop();
 
	//Quit the engine
	AnnQuit();
	return EXIT_SUCCESS;
}

Beside loading the engine and starting the render loop, this code does nothing really special. You absolutely have to specify a name for your application. This string of text is used to create the window of the application, and by other components, like the AnnFileSystemManager

Including libs

The only header you are required to include is Annwvyn.h.

#include <Annwvyn.h>

For speeding the build process, the template project uses “precompiled headers”. Visual Studio is fairly slow to pre-process included headers. Including Annwvyn also include all the needed modules of your game : sound, physics, graphics, VR tracking, rendering, input management, scripting… These also include a bunch of libraries that are needed to support their functionalites.

Precompiling the header permit to avoid having to parse all the include statement of all the files in the engine and it's included libraries. It will only be done if you either, rebuild from scratch your application, or if the library headers change.

For this system to work, the first line of any .cpp file of the project needs to be

#include "stdafx.h"

The first time you hit compile, it will pre-built the headers via the stdafx.cpp file. This can take some time, but it should do it only once.

Initialize the engine

main function declaration

For diverse reasons (command line argument parsing. Selection of the entry point between multiple OSes, hook for per-initialization of development facilities…), the main function declaration is overridden by a macro on Annwvyn. You application entry point is

AnnMain()
{
//...
}

Using this construct permit you to start and stop the engine with the AnnInit() and AnnQuit() macros. They aren't mandatory, but they permit to hide some rough edges of the initialization process.

Load the engine

namespace

All Annwvyn classes, functions, types and other things are in the Annwvyn namespace. If you want you can declaring you use this namespace

using namespace Annwvyn;

AnnEngine object

The main class of Annwvyn is AnnEngine. AnnEngine initialize all Annwyvn's intenal components.

AnnEngine is also the central access point for talking to other Annwvyn components. It's like the conductor of the Annwvyn orchestra ;-)

First thing you should do is to dynamically allocate AnnEngine. This can be done with the macro AnnInit().

You absolutely need to give your application a name, as a string, passed to AnnInit

AnnInit("MyVirtualRealityApp");

The AnnEngine class is following the “Singleton” design pattern. You're program will crash if you dare to declare two different AnnEngine instance.

You can access the unique instance of AnnEngine via AnnEngine::Instance(), or (preferably since it's shorter) the getter function AnnGetEngine(). This call will return nullptr if the engine is not running

This is a simplified version of what AnnEngine looks like:

You can acces pointers to the important parts of Annwvyn via AnnEngine's getters. Notable mentions are the AnnPlayer, AnnPhysicsEngine, AnnAudioEngine, AnnLevelManager, AnnEventManager (more information on the API documentation). They are all avalable as AnnGetSomething

Loading Ressources

Before anything else, you should load the resources you will use into the engine.

Resources are all the assets your game will use. 3D objects, textures, sound effects, script files, etc…

Currently, you have 2 choices :

  • Put your resources on directories and load them with AnnGetResourceManager()→addFileLocation(const char path[])
  • put them on a zip files and load them with AnnGetResourceManager()→addZipLocation(const char path[]). Note that you don't need that file to terminate with the .zip extension

Example :

AnnGetResourceManager()->addFileLocation("media/dome");
AnnGetResourceManager()->addZipLocation("media/Sinbad.zip");

The “media” subdirectory is loaded by default by the engine, as the CORE.zip file in it.

This file contain vital data that Annwvyn itself need to initialize, and the data fro the testing programs.

When you are done adding the resource locations, don't forget to call;

AnnGetResourceManager()->initResources();

Resources will not be available before this.

Annwvyn will load the resources in memory as the are used. There's a way for you to put them in “named groups”, and to pre-load them at will.

Annwvyn uses Ogre's own “resource group manager” internally. You still have access to it. Annwvyn also employ simple custom “Resource Manager” for Ogre internally to load audio file and gameplay scripts written in ChaiScript. All of your game resources are pulled from Ogre's system.

Annwvyn will always add ./media and ./media/CORE.zip as resource locations. CORE.zip contains various elements that are expected to allways be available for the game engine. Theses places are called Annwvyn Core resources

Resource format

Annwvyn uses Ogre for rendering graphics and handling most of the 3D geometry it needs to process, compiled with freeimage. Ogre is compatible with almost any image file format but 3D object needs to uses Ogre's own filetype.

Putted simply:

  • 3D Object: Ogre .mesh binary format, in version 1.x, with their accompanying skeleton format.
  • Material description: Ogre .material script, containing HLMS PBS or HLMS UNLIT materials. They can also be JSON scripts.
  • Textures: 2D image
  • Audio: Any file format readable by libsndfile. Basically everything relevant, except MP3, because patent laws.
  • Scripts: File written in ChaiScript. Notably Object “Behavior Scripts” that can be attached to them.

The Game loop

Annwvyn has an internal loop that will, by default, run infinitely until the user press ESC

You can start this loop by calling

	AnnGetEngine()->startGameplayLoop();

If you haven't created and jumped to a level, or manually created GameObjects before, you'll be on an empty scene with a blue-sky background. This is normal and indicate that everything is working properly. And we will change that soon. but before that, you may want to control the gameplay loop yourself to add you own stuff (like if you need to put integration code for some weird peripheral like a LEAP motion or something). Although, Annwvyn is a framework that support being you to register “subsystems” that will be updated by the engine. So you can insert arbitrary code inside the default gameplay loop. The mindset to have is “I give code to be called by Annwvyn” once the loop started, not the other way around.

But, you are free to do what you want. And you can set-up that loop manually by doing :

//--Use the built-in termination check (has ESC been pressed)
do
{
//Custom stuff
}while(AnnGetEngine()->refresh());
 
//--Use you own termination
do
{
//Custom stuff
 
//Last thing to do: call engine refresh
AnnGetEngine()->refresh();
}while(conditionToContinue);

Note: Annwvyn's level manager may take up to two frames to engage the level loading. This is due to the fact that level loading is a slow operation, and priority was given to the event processing. The LevelManager deffer the level loading to let all event-related call terminate. Thus, you may see that your selected first level isn't running for one or two loop iteration.

quickstart.txt · Last modified: 2017/10/23 09:59 by ybalrid