This is a basic C++ tutorial showing how to write a stand alone executable using orx.
As we are *NOT* using the default executable anymore for this tutorial, the tutorial
code will be directly in the executable and not in an external library.

We thus are able to specify what we need (physics or not, display or not, etc...).
However we will *NOT* have the default hardcoded behavior:
- F11 will not affect vertical sync toggler
- Escape won't exit
- Backspace won't reload configuration files
- the [Main] section in the config file won't be used to load a plugin ("GameFile" key)

Our program will also *NOT* exit if it receives the orxSYSTEM_EVENT_CLOSE event.
To do so, we will either have to use the helper orx_Execute() function (see below)
or handle it ourselves.

Not using the default executable will also remove the automated help display (-h parameter)
and the default random seed setup.

Important: please also note that if you want to link your own executable against a dynamically linked version of orx library, you need to provide the __orxDLL__ preprocessor flag!

See previous tutorials for more info about the basic object creation, clock, animation,
viewport, sound, FX, physics/collision and differentiel scrolling handling.

This tutorial shows how to create your stand alone game using orx as a library.

As we're on our own here, we need to write the main function and initialize orx manually.
The good thing is that we can then specify which modules we want to use, and deactivates display
or any other module at will, if needed.

If we still want a semi-automated initialization of orx, we can use the orx_Execute() function.
This tutorial will cover the use of orx with this helper function, but you can decide not to use
it if its behavior doesn't suit your needs.

This helper function will take care of initializing everything correctly and exiting properly.
It will also make sure the clock module is constantly ticked (as it's orx's core) and that
we exit if the orxSYSTEM_EVENT_CLOSE event is sent.
This event is sent when closing the windows, for example, but it can also be sent under
your own criteria (escape key pressed, for example).
We'll see that even if this event is handled by default, we can still override it.
To give an example, this tutorial won't close using the default scheme as you will see in its code.

This code is a basic C++ example to show how to use orx without having to write C code.

This tutorial could have been architectured in a better way (cutting it into pieces with headers files, for example)
but we wanted to keep a single file per *basic* tutorial.

This stand alone executable also creates a console (as does the default orx executable),
but you can have you own console-less program if you wish. You only need to provide an arc/argv style
parameter list that contains the executable name, otherwise the default config file will be
orx.ini instead of 10_StandAlone.ini here.

For windows visual studio users, it can easily be achieved by writing a WinMain() function instead of main(),
and by getting the executable name (or hardcoding it).

This tutorial simply display an orx logo, and will only exit if backspace is pressed. If you try to exit using
the windows 'X' button or by pressing alt-F4, a message will be displayed and the logo color will change.

Some explanations about core elements you can find in this tutorial:

  • Setup function: usually used to define module dependencies.
    Here we add dependencies for the main module (our code).
    This specifies a hierarchical tree used for modules init, exit and pause.
    For our program to run, we require the param, clock, config, event and plugin modules to be loaded before us.
    They all have their internal dependencies that must be satisfied before they can be initialized. If a dependency can't be satisfied initialization will stop.
    For example, if the clock module can't initialize properly, as we depend on it, our Init() function will never be called.
    We can specify optional dependencies using the orxModule_AddOptionalDependency(). This way, orx will try to init the concerned module but won't stop initialization if it fails.
  • Run function: Don't put *ANY* logic code here, it's only a backbone where you can handle default core behaviors (tracking exit, for example) or profile some stuff.
    As it's directly called from the main loop and not part of the clock system, time consistency can't be achieved.
    For all your main game execution, please create (or use an existing) clock and register your callback to it.
  • Event handlers:
    When an event handler returns orxSTATUS_SUCCESS, no other handler will be called after it for the same event.
    For example, that's how we inhibit the default exit behavior for orxSYSTEM_EVENT_CLOSE event.
    On the other hand, if orxSTATUS_FAILURE is returned, event processing will continue for this one if other handlers are listening this event type.
  • orx_Execute():
    Inits and executes orx using our self-defined functions (Setup, Init, Run and Exit).
    We can of course not use this helper and handles everything manually if its behavior doesn't suit our needs.
    You can have a look at the content of orx_Execute() (which is implemented in orx.h) to have a better idea on how to do this.

Download source code: 10_StandAlone.cpp

Download config file: 10_StandAlone.ini