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, and open the “Game.sln” solution into Visual Studio 2015.

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 and rendering and input management.

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

The main function declaration is overridden by a macro on Annwvyn. You application entry point is

AnnMain()
{
//...
}

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 be put to early termination 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 macro 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.

You have 2 choices :

  • Put your resources on directories and load them with AnnGetResourceManager()→addFileLocation(const char path[])
  • put them on .zip files and load them with AnnGetResourceManager()→addZipLocation(const char path[])

Example :

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

When you have finish, don't forget to call

AnnGetResourceManager()->initResources();

Resources will not be available before this.

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 handleing most of the 3D geometry it needs to process, compilled 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
  • Auido : Any file format readable by libsndfile. Basically everything relevant, except MP3, because patent laws.

The Game loop

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

You can start this loop by calling

	AnnGetEngine()->startGameplayLoop();

If you havent 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 support you to register “subsystems” that will be updated by the engine. So you can insert arbitrary code inside the default gameplay loop.

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 check
do
{
//Custom stuff
 
//Last thing to do: call engine refresh
AnnGetEngine()->refresh();
}while(conditionToContinue);
quickstart.txt · Last modified: 2017/08/19 22:47 by ybalrid