BansheeEngine/Documentation/Manuals/Native/gettingStarted.md

Getting started {#gettingStarted}

[TOC]

This manual offers a quick overview of commonly used Banshee functionality, in order to give you a better idea of how Banshee works. For a fully working example check out the ExampleProject project available with the source code.

Starting an application

Banshee is started through the @ref BansheeEngine::Application "Application" interface. To start the engine you need to provide it with a description of the primary render window and choose which modules to load. Since Banshee is a plugin based engine you have a selection between multiple modules for each system like render API or physics, and a set of completely optional plugins (like importers for various file formats).

After the application is started by calling @ref BansheeEngine::Application::startUp "Application::startUp", you can set up your custom code in the form of @ref BansheeEngine::Component "components" (see later). After that you can run the main loop with @ref BansheeEngine::Application::runMainLoop "Application::runMainLoop" which will execute your code and actually get everything in motion.

Once the main loop terminates use @ref BansheeEngine::Application::shutDown "Application::shutDown" to clean everything up.

// Descriptor used for initializing the engine
START_UP_DESC startUpDesc;

// Choose which plugins to load. In this case use the default values as specified by the build system.
startUpDesc.renderAPI = BS_RENDER_API_MODULE;
startUpDesc.renderer = BS_RENDERER_MODULE;
startUpDesc.audio = BS_AUDIO_MODULE;
startUpDesc.physics = BS_PHYSICS_MODULE;
startUpDesc.input = BS_INPUT_MODULE;

// List of optional importer plugins we plan on using for importing various resources.
startUpDesc.importers.push_back("BansheeFreeImgImporter"); // For importing textures
startUpDesc.importers.push_back("BansheeFBXImporter"); // For importing meshes
startUpDesc.importers.push_back("BansheeFontImporter"); // For importing fonts
startUpDesc.importers.push_back("BansheeSL"); // For importing shaders

// Descriptor used for initializing the primary application window.
startUpDesc.primaryWindowDesc.videoMode = VideoMode(windowResWidth, windowResHeight);
startUpDesc.primaryWindowDesc.title = "Banshee Example App";
startUpDesc.primaryWindowDesc.fullscreen = false;
startUpDesc.primaryWindowDesc.depthBuffer = false;

Application::startUp(startUpDesc);
... set up game code ...
Application::instance().runMainLoop();
Application::shutDown();

Read the render targets manual for more information about creating render windows, and the game objects manual on how to create your own components.

Importing resources

To import a resource from a third party format into an engine-readable format use the @ref BansheeEngine::Importer "Importer" module. A variety of formats like PNG, JPG, PSD, FBX, etc. are supported. Read the importer manual for more information about importers.

In the example below we'll import a @ref BansheeEngine::Mesh "Mesh" and a @ref BansheeEngine::Texture "Texture".

HMesh dragonModel = gImporter().import<Mesh>("Dragon.fbx");
HTexture dragonTexture = gImporter().import<Texture>("Dragon.psd");

Setting up a material

Once we have a mesh and a texture we need some way to apply that texture to the mesh. For that reason we first import a @ref BansheeEngine::Shader "Shader" that describes how is an object rendered, which we then use to create a @ref BansheeEngine::Material "Material" which allows us to apply our previously loaded @ref BansheeEngine::Texture "Texture".

Read the material manual for more information about shaders and materials.

HShader diffuse = gImporter().import<Shader>("Diffuse.bsl");
HMaterial dragonMaterial = Material::create(diffuse);

dragonMaterial->setTexture("albedo", dragonTexture);

Adding an object for rendering

To actually make our mesh render with our material, we need to add a @ref BansheeEngine::SceneObject "SceneObject" onto which we attach a @ref BansheeEngine::CRenderable "CRenderable" component. This component allows us to set up a mesh and a material, after which they will be automatically rendered to the active camera.

To learn more about @ref BansheeEngine::SceneObject "scene objects" and @ref BansheeEngine::Component "components" read the game object manual. You can use the same approach we followed here to add your own custom components, containing custom code.

You can also read up on the renderer manual to learn more about how the @ref BansheeEngine::CRenderable "CRenderable" components works.

HSceneObject dragonSO = SceneObject::create("Dragon");

HRenderable renderable = dragonSO->addComponent<CRenderable>();
renderable->setMesh(dragonModel);
renderable->setMaterial(dragonMaterial);

Adding a scene camera

In order to actually see our object we need to set up a camera. First create a new @ref BansheeEngine::SceneObject "SceneObject" onto which you can then attach a @ref BansheeEngine::CCamera "CCamera" component. After that we position the @ref BansheeEngine::SceneObject "SceneObject" so it is looking at the object we set up in previous steps.

HSceneObject sceneCameraSO = SceneObject::create("SceneCamera");
HCamera sceneCamera = sceneCameraSO->addComponent<CCamera>(window);

sceneCameraSO->setPosition(Vector3(40.0f, 30.0f, 230.0f));
sceneCameraSO->lookAt(Vector3(0, 0, 0));

Adding a GUI element

Finally you might want to add a GUI to your application. Similar to above, create a new @ref BansheeEngine::SceneObject "SceneObject" onto which we add a new @ref BansheeEngine::CCamera "CCamera" used only for rendering GUI. Since we don't want it to render normal scene objects, we let it's filter layers to 0.

We also add a @ref BansheeEngine::CGUIWidget "CGUIWidget" component onto the same @ref BansheeEngine::SceneObject "SceneObject", which is used as a container for all GUI elements. After that we add a couple of @ref BansheeEngine::GUIButton "GUIButtons" to the GUI.

Read the GUI manual for more information about GUI.

HSceneObject guiSO = SceneObject::create("GUI");

HCamera guiCamera = guiSO->addComponent<CCamera>(window);
guiCamera->setLayers(0); // Force camera to ignore normal scene geometry

HGUIWidget gui = guiSO->addComponent<CGUIWidget>(guiCamera);
GUIPanel* guiPanel = gui->getPanel();

GUILayout* guiLayout = guiPanel->addNewElement<GUILayoutY>();
guiLayout->addNewElement<GUIButton>(HString(L"Click me!"));
guiLayout->addNewElement<GUIButton>(HString(L"Click me too!"));

There is a lot more to Banshee, but hopefully this gave you a quick taste of how it works. Continue reading other manuals and the API reference for more information.