Ultra Game Template

[reepblue]

Back in July, I talked about the idea of building a compartmentalized base application for Ultra Engine. I now want to share what I've been working on and my future plans going forward. 

This foundation in which I'm dubbing "The Ultra Game Template" is base code and assets to help developers start their next project right. The goal was to have a base layer that did all the "not so fun" but critical elements when building a game such as scene management, input handling, window resizing, etc. 

The scene/map space is left alone and attaching components works the same if you started your project from scratch and a lot of the back-end stuff can be customized via the config.json file. Here's a list of some of the features.

Splash Screen

A splash screen is sometimes required for displaying legal notices and is useful for showing the end user that the application is loading in the background. The splash screen can be customized via the config file or disabled entirely. It should also look very familiar. :^) 

 

Built-In Settings

All engine settings are exposed file the built-in settings window. You no longer need to tell testers to edit any config files ever again! They can now freely change their target display, resolution, graphic settings, and key bindings! 

 

Dynamic, Configurable and Easy-To-Use Input System.

Coming from the input system from Cyclone, the template has support for key bindings. This is modeled after Steam Input where everything is defined as an action and can be contained in action sets. You can bind the same key to different actions in separated sets.  

Defining a base scheme is simple as making a function in the main.cpp file and passing the game controller pointer through it.

// Define default controls.
static void InstallControls(shared_ptr<GameController> controller)
{
    if (controller == NULL) return;

    // Program actions
    controller->SetAction("Pause", BUTTON_KEY_ESCAPE);
    controller->SetAction("Terminate", BUTTON_KEY_END);
    controller->SetAction("ConsoleApp", BUTTON_KEY_F1);
    controller->SetAction("Fullscreen", BUTTON_KEY_F11);
    controller->SetAction("Screenshot", BUTTON_KEY_F2);
    controller->SetAction("Quick Save", BUTTON_KEY_F5);
    controller->SetAction("Quick Load", BUTTON_KEY_F6);

    // Camera
    ButtonAxis moveaxis =
    {
        BUTTON_KEY_W,
        BUTTON_KEY_S,
        BUTTON_KEY_A,
        BUTTON_KEY_D
    };
    controller->SetAction("Movement", moveaxis, "InGameControls");
    controller->SetAction("Sprint", BUTTON_KEY_SHIFT, "InGameControls");
    controller->SetAction("Crouch", BUTTON_KEY_CONTROL, "InGameControls");
    controller->SetAction("Climb", BUTTON_KEY_Q, "InGameControls");
    controller->SetAction("Desent", BUTTON_KEY_E, "InGameControls");
    controller->SetAction("Camera", AXIS_MOUSE, "InGameControls");

    // Settings
    controller->SetSetting("Raw Mouse", false);
    controller->SetSetting("Inverse Mouse", false);
    controller->SetSetting("Mouse Smoothing", 0.0f);
    controller->SetSetting("Mouse Look Speed", 1.0f);
}

Then in the settings application will build the binding list for you separating the sets and settings into their own tabs. 

All of this is built using the engine's API so it's cross platform compatible! 

 

Event Based Console

A developer console is something you can't live without when developing a game. When called (Default F1), a console window will pop up and will await your input. The commands are event based and there's no registering of commands required. 

Just put something like this in your component's ProcessEvent function.

        if (e.id == EVENT_CONSOLEEXECUTE)
        {
            auto line = e.text.Split(" ");
            auto cmd = line[0].ToString();
            if (line.size() > 1 && !line[1].empty())
            {
                if (cmd == "mycommand")
                {
                    Print("Applied command " + QuoteString(cmd) + " to: " + line[1]);
                }
            }
        }

Existing commands are:

• map - loading maps (Example: map box)
• restart - Restart the existing map.
• clear - Clears the current map. 
• quit - Terminates the application.

 

You can download it here. 

 

[reepblue]

I re-arranged the source code so it's isolated from everything else in your project. It's less of a template and more of a system you drop in and call from your main.cpp file. I think I'll be shipping just this folder and the config.json file.

As for the main.cpp, I think I'm just going to post an example of one in the readme. But it's not that complicated. The idea is you register your components and input controls here. You can also install a custom loading screen if you don't like the default one. 

#include "UltraEngine.h"
#include "Game/Game.h"
using namespace UltraEngine;
using namespace UltraEngine::Game;

// Components
#include "Components/Motion/Mover.hpp"
#include "Components/Player/CameraControls.hpp"

static void RegisterComponents()
{
    RegisterComponent<Mover>();
    RegisterComponent<CameraControls>();
}

// Define default controls.
static void InstallControls(shared_ptr<GameController> controller)
{
    if (controller == NULL) return;

    // Program actions
    controller->SetAction("Pause", BUTTON_KEY_ESCAPE);
    controller->SetAction("Terminate", BUTTON_KEY_END);
    controller->SetAction("ConsoleApp", BUTTON_KEY_F1);
    controller->SetAction("Fullscreen", BUTTON_KEY_F11);
    controller->SetAction("Screenshot", BUTTON_KEY_F2);

    // Camera
    ButtonAxis moveaxis =
    {
        BUTTON_KEY_W,
        BUTTON_KEY_S,
        BUTTON_KEY_A,
        BUTTON_KEY_D
    };
    controller->SetAction("Movement", moveaxis, "InGameControls");
    controller->SetAction("Sprint", BUTTON_KEY_SHIFT, "InGameControls");
    controller->SetAction("Crouch", BUTTON_KEY_CONTROL, "InGameControls");
    controller->SetAction("Climb", BUTTON_KEY_Q, "InGameControls");
    controller->SetAction("Desent", BUTTON_KEY_E, "InGameControls");
    controller->SetAction("Camera", AXIS_MOUSE, "InGameControls");
    controller->SetAction("Jump", BUTTON_KEY_SPACE, "InGameControls");

    // Settings
    controller->SetSetting("Raw Mouse", false);
    controller->SetSetting("Inverse Mouse", false);
    controller->SetSetting("Mouse Smoothing", 0.0f);
    controller->SetSetting("Mouse Look Speed", 1.0f);
}

int main(int argc, const char* argv[])
{
    // Register Components.
    RegisterComponents();

    // Init the program!
    auto app = GetProgram();
    app->commandline = ParseCommandLine(argc, argv);

    if (!app->Initialize())
        return 1;

    // Load all plugins.
    if (!app->LoadPlugins())
    {
        Print("Warning: Failed to successfully load all plugins!");
    }

    // Load packages
    if (!app->LoadPackages())
    {
        Print("Warning: Failed to load one or more packages.");
    }

    // Load Settings
    if (!app->LoadSettings())
    {
        Print("Warning: Failed to load program settings.");
    }

    // Set the correct program app type based on the commandline.
    ProgramApp programtype = PROGRAMAPP_GAME;
    if (app->commandline[CFLAG_SETTINGSAPP] == true)
    {
        programtype = PROGRAMAPP_SETTINGS;
    }
    else if (app->commandline[CFLAG_LUASCRIPT] == true)
    {
        programtype = PROGRAMAPP_LUASCRIPT;
    }

    // Init the game controller.
    app->gamecontroller = CreateGameController();
    InstallControls(app->gamecontroller);
    if (!app->LoadControllerBindings())
    {
        Print("Warning: Failed to load controller bindings.");
    }

    // Launch the app.
    if (app->LaunchApp(programtype) == false) return 1;

    // Install the loading screen.
    app->stage->SetLoadingScreen<LoadingScreen>();

    // Main Loop
    bool running = true;
    while (running)
    {
        while (PeekEvent())
        {
            const auto e = WaitEvent();
            if (!app->ProcessEvent(e))
            {
                EmitEvent(EVENT_QUIT);
            }

            if (e.id == EVENT_QUIT)
            {
                if (app->Shutdown())
                {
                    if (!app->SaveSettings())
                    {
                        Print("Error: Failed to save program settings.");
                    }

                    running = false;
                    break;
                }
            }
        }

        app->Update();
    }

    // Write this line before we terminate!
    Print("Application terminated successfully!");

    return 0;
}

 

[reepblue]

It's now live! Blog post will follow soon! 

[klepto2]

Wow, this is really amazing and it is very nice to share this gem. I am looking forward for the blog entry.

Some small ideas after a short look into the code: 

• The Print outputs in some classes could be managed by some kind of log manager.  With redirecting to error logs etc...
• While the ParseCommandline and the table class is very powerful, I would use a more abstract and typesafe way for the commandlines

in the PBR Texture Generator i use this gem: https://github.com/jarro2783/cxxopts/tree/master for command line handling:

the usage is very simple and straight forward:

bool showhelp = false;
    bool batch = false;
    bool cubemap = false;
    bool panorama = false;
    string outdir;
    string dir;
    string file;
    int samples;
    float lodbias;
    float exposure;
    int diffuse_res;
    int specular_res;

    cxxopts::Options options("UltraPBRTextureGen.exe", "this tool generates the required PBR textures from panorama HDR files or Cubemaps (*.dds or *.tex) files");
    options.allow_unrecognised_options();
    options.add_options()
        ("b, batch", "Batch operations", cxxopts::value<bool>(batch)->default_value("false")) // a bool parameter
        ("c, cubemap", "Convert cubemaps (dds, tex)", cxxopts::value<bool>(cubemap)->default_value("false"))
        ("p, panorama", "Convert panoramas (hdr)", cxxopts::value<bool>(panorama)->default_value("false"))
        ("d, dir", "path to search the files (only used with batch option)", cxxopts::value<std::string>(dir))
        ("o, out", "output folder", cxxopts::value<std::string>(outdir))
        ("f, file", "file to convert (only when not used with batch option)", cxxopts::value<std::string>(file))
        ("e, exposure", "Exposure to be used when importing HDR images", cxxopts::value<float>(exposure)->default_value("4.0"))
        ("s, samples", "Samples to be used", cxxopts::value<int>(samples)->default_value("1024"))
        ("lb, lodbias", "LodBias to be used", cxxopts::value<float>(lodbias)->default_value("0.0"))
        ("dr, diffuse_resolution", "Resolution for the diffuse map", cxxopts::value<int>(diffuse_res)->default_value("128"))
        ("sr, specular_resolution", "Resolution for the specular map", cxxopts::value<int>(specular_res)->default_value("1024"))
        ("h,help", "Show help", cxxopts::value<bool>(showhelp)->default_value("false"));


    auto result = options.parse(argc, argv);

 	if (showhelp)
    {
        Print(options.help());
        return 0;
    }

 

[reepblue]

Although cxxopts looks interesting, I wanted to stay exclusive to the engine's API for this. I didn't want to do anything that could/would change the workflow of how things are normally done with the engine.

I might consider separating the logs by type though, I already have it sorted by colors at this point. 

[Josh]

Your little command language looks cool. This is probably more useful than exposing full Lua programming.

What are the extents/limitations of the syntax? Is it just "command arg1, arg2, arg3?"

[reepblue]

14 minutes ago, Josh said:

Your little command language looks cool. This is probably more useful than exposing full Lua programming.

What are the extents/limitations of the syntax? Is it just "command arg1, arg2, arg3?"

One of the things I don't like is that you need to cut the full line of text by spaces every time. The system I had for Cyclone only had the arguments available in a vector.  This is a limitation of the Event System, but having it event based makes commands less static and it's way easier to do component based commands.

One thing I still don't like thats in both systems is you need to do size checks on the argument vector before using it to prevent crashing. Other than that, it's a canvas for the programmer to do whatever they need done. 

[klepto2]

On 10/29/2023 at 2:51 AM, reepblue said:

Although cxxopts looks interesting, I wanted to stay exclusive to the engine's API for this. I didn't want to do anything that could/would change the workflow of how things are normally done with the engine.

I might consider separating the logs by type though, I already have it sorted by colors at this point. 

Valid point. It is always good to use the provided api. Also, it is not hard to switch this out when needed. 

Just a small snippet I used in the Texture Gen to get proper redirection in windows apps which have no console:

if (!AttachConsole(ATTACH_PARENT_PROCESS))
        {
            if (AllocConsole())
            {
                freopen("conin$", "r", stdin);
                freopen("conout$", "w", stdout);
                freopen("conout$", "w", stderr);
            }
        }
        else
        {
            auto consoleHandleOut = GetStdHandle(STD_OUTPUT_HANDLE);
            auto consoleHandleIn = GetStdHandle(STD_INPUT_HANDLE);
            auto consoleHandleErr = GetStdHandle(STD_ERROR_HANDLE);
            if (consoleHandleOut != INVALID_HANDLE_VALUE) {
                freopen("conout$", "w", stdout);
                setvbuf(stdout, NULL, _IONBF, 0);
            }
            if (consoleHandleIn != INVALID_HANDLE_VALUE) {
                freopen("conin$", "r", stdin );
                setvbuf(stdin, NULL, _IONBF, 0);
            }
            if (consoleHandleErr != INVALID_HANDLE_VALUE) {
                freopen("conout$", "w", stderr);
                setvbuf(stderr, NULL, _IONBF, 0);
            }
        }

This is useful if you compile an UltraEngine app in release, but also want to mix cmdline features with a standard window app. This redirects the output to the console window if possible (e.G: when running from a batch file) otherwise it creates a new console (eg when it is used without a batch, but with a link-file).   

[reepblue]

A few changes:

• This is now installable as a Template. Copy the "C++ Game" into the engine's Template folder and create a new project off of that. I didn't redistribute any SDK files so right now the start.ultra map will not work unless you were to copy over the stock components yourself. 
• Removed start.ultra from the config's start map to prevent said issues. 
• Visual Studio project is now included with all files added. 
• My Component Preprocesor is now being used to make the component registration much more seamless. 
• The app icon is now orange.
• Fixed any issues causing build errors. 

Some things I'm considering:

• Create a new start.ultra map to override the stock one.
• Ship my own components making use of the rest of the system. 
• I've got more developer textures. I was going to ship it in its own package. I'm not sure including it would more help or bother people. 
• Editing the template solution is really annoying. I might revive my premake setup. This will really help when Ultra Engine goes multiplatform. 

 

[Josh]

It says the preprocessor exited with an error code?

error MSB3073: :VCEnd" exited with code 9009

[reepblue]

My guess is that Windows is blocking the direct execution because it's a foreign app.  Manually run the application tell UAC to trust the app. 

Or build try building the Preprocessor from the GitHub and use your version. Ether way, I didn't factor that into account. 🫢

[klepto2]

2 hours ago, reepblue said:

My guess is that Windows is blocking the direct execution because it's a foreign app.  Manually run the application tell UAC to trust the app. 

Or build try building the Preprocessor from the GitHub and use your version. Ether way, I didn't factor that into account. 🫢

thats it

I have tested the template a bit and found a few things:

• the settings.bat file is not updated with the template name
• it would be nice to have the console enabled in the sample by default
• adding the console window and sending an empty command causes a crash
• closing the console window doesn't resume the scene
• TODOS: 
  • Terminate behavior (IDEAS)
    • Add a callback function to the terminate method 
    • default show a message box "Do you really want to quit?"
    • This could be extended to allow something like Back to Main menu or Back to Desktop
• Using the sample scene (don't know if this is a bug in UltraEngine or the template) saving a quick save and reloading disables the door component. The close or open state works, but after the closing or opening the trigger will not work anymore

Some ideas for the template itself:

• Try to add some more samples showing the intended workflow (e.g.: Main-Menu, loading and saving, in game options)
• Provide an in game console which did not need an actual window. (the console is very nice, but it is a bit of the mainstream if another window is opening, especially when the app is running in full screen)

[Josh]

Also, if you can build the preprocessor with Ultra App Kit you will get a much smaller executable.

[reepblue]

Pushed out an update.

• Settings.bat has $PROJECTNAME token so the template system will swap it with the name of the project (untested)
• Both Debug and Release builds are Windowed applications to have a cleaner appearance launching from the editor. 
• Replaced CallCMDWindow() function with what @klepto2 posted above. (Launch the app with -cmd to make the console window.)
• Prevented empty strings being sent through the console event. 
• Terminate() now asks if you really mean to force close the application. Sorta annoying but it feels much cleaner. Now you know if your game closes without asking, it's decently a crash. (To close the game without a confirmation, just emit EVENT_QUIT. Terminate is only used to get you out of a sticky situation.)
• Added a note about UAC and the Component Preprocessor. 

 

15 hours ago, klepto2 said:

closing the console window doesn't resume the scene

This is kind of tricky to do since we need to store the previous pause state and I'm not sure where to store it. The softlock is due to the stock Components not being setup to unpause the game. 

 

15 hours ago, klepto2 said:

Using the sample scene (don't know if this is a bug in UltraEngine or the template) saving a quick save and reloading disables the door component. The close or open state works, but after the closing or opening the trigger will not work anymore

Must be the component/engine. The system just calls World::Save()/World::Load() functions. 

 

15 hours ago, klepto2 said:

Some ideas for the template itself:

• Try to add some more samples showing the intended workflow (e.g.: Main-Menu, loading and saving, in game options)
• Provide an in game console which did not need an actual window. (the console is very nice, but it is a bit of the mainstream if another window is opening, especially when the app is running in full screen)

In due time. This went from being something you dropped in your existing project to a full template. I decided to go this route because adding all the files was tedious, and it helps prevent any conflicts Josh may want to push out. 

 

6 hours ago, Josh said:

Also, if you can build the preprocessor with Ultra App Kit you will get a much smaller executable.

Just set up a UAK project. I had to change a few things so I'm gonna battle test it before releasing it. But yes, went from 20MB to 744KB! 

[klepto2]

9 hours ago, reepblue said:

Must be the component/engine. The system just calls World::Save()/World::Load() functions. 

I think the same, will investigate it further and file a bug report on this

9 hours ago, reepblue said:

In due time. This went from being something you dropped in your existing project to a full template. I decided to go this route because adding all the files was tedious, and it helps prevent any conflicts Josh may want to push out. 

That is fully understandable, I just wanted to point out that, once the system is stable and feature ready enough (and UltraEngine itself as well), you should consider to add some advanced sample as a documentation. But to be fair, this is a free piece of code and is a already a great starting point for anyone who wants to start developing with Ultraengine.

9 hours ago, reepblue said:

This is kind of tricky to do since we need to store the previous pause state and I'm not sure where to store it. The softlock is due to the stock Components not being setup to unpause the game. 

One thing that comes into my mind is: why doing a pause generally. The easiest solution might be to don't pause at all and leave it up to the developer. As a reference the ingame consoles in most games don't pause (i can't really think of any game which pauses the game in this case)

 

9 hours ago, reepblue said:

• Terminate() now asks if you really mean to force close the application. Sorta annoying but it feels much cleaner. Now you know if your game closes without asking, it's decently a crash. (To close the game without a confirmation, just emit EVENT_QUIT. Terminate is only used to get you out of a sticky situation.)

maybe an optional parameter can be used, something like "Terminate(bool force = false, int closeReason = 0);". This could be used in case of errors.

[klepto2]

12 hours ago, reepblue said:

Must be the component/engine. The system just calls World::Save()/World::Load() functions. 

Found the bug in the component itself:

 

[reepblue]

On 11/1/2023 at 4:06 AM, klepto2 said:

One thing that comes into my mind is: why doing a pause generally. The easiest solution might be to don't pause at all and leave it up to the developer. As a reference the ingame consoles in most games don't pause (i can't really think of any game which pauses the game in this case)

This will be fixed in the next update. The console will no longer pause the game. It will instead change the Action Set to null before storing the previous set. Then it'll reapply the last Action Set when it's closed. I tried making it swap Action Sets based on what window was selected but I got weird results. I think it's time to make an in-game one and only have this as a fallback.

You'll now be able to set mouse cursor types to an Action Set. It'll tell the application to swap cursors when SetActionSet() is called. If one isn't set, the default cursor will be used.

controller->SetActionSetCursor("InGameControls", CURSOR_NONE);

The only thing that'll pause your game is if you press the assigned Pause action key. Not even Terminate will pause the game.

[reepblue]

New build is up.

This has the hands-off approach to pausing and the new SetActionSetCursor function for the game controller. Bug fixes and other small adjustments have are also included.

There is also commented code for the Console as I was experimenting with how it should work. I've reached the conclusion that the Console Window will be enabled by a macro define by default. The next step regarding this is to restructure how UI Elements can work. You should be able to draw the same UIElement with the Interface or in Vulkan. This will also be useful for the settings too. 

Last, the Preprocessor application is the UAK version cutting down in file sizes.  

[reepblue]

Pushed a new build today with VR Intergration!

You can easily enable VR in your project in one or two ways;

• Use the -vr argument.
• If your game is a dedicated VR application, you can force VR by making a new table in the config.json file. 

"engine"
{
	"vr": true
}

You can also use the engine table to define the rest of the engine settings, but tread carefully! If you wish to temporarily disable VR, then use the -novr argument. 

The Preprocessor was updated with the change today and I removed the GameObject class. I'm still playing with components so a future update will come eventually. 

The solution doesn't include the System Environment edit or any recent changes. I'm going to be syncing the solution files at a later date.

[reepblue]

Push an update today fixing VR support. I also changed how you define if your app is a dedicated VR app. See the config.json file for details.

Removed the ConsoleWindow and SettingsWindow and put all the code into a PanelUI class which can be used both in a window and within the Vulkan Renderer. Lastly, I refreshed the solution files to reflect the changes made to the ones shipped in the stock C++ template. 

[kasool]

The blank scene seems to load properly but I do get some warnings/errors:

 

Btw I was able to install by running the Install Template.bat as an admin. Manually executing Preprocessor.exe as an admin didn't seem to do anything in my case.

[reepblue]

1 hour ago, kasool said:

The blank scene seems to load properly but I do get some warnings/errors:

That's normal for a first boot. You can fix the warnings by launching the app with -Settings and save down the default settings/controls. The error message is from the engine itself. If you're not using Lua, don't worry about it. If it bugs you, just make a blank file in it's place.

1 hour ago, kasool said:

Btw I was able to install by running the Install Template.bat as an admin. Manually executing Preprocessor.exe as an admin didn't seem to do anything in my case.

Running the Preprocessor as admin should tell Windows to trust it going forward. If you're having issues getting the application to auto generate your component list, let me know. It works for me because I compile the application which you can also do since I have the code for that linked in my signature. 

[kasool]

44 minutes ago, reepblue said:

That's normal for a first boot. You can fix the warnings by launching the app with -Settings and save down the default settings/controls. The error message is from the engine itself. If you're not using Lua, don't worry about it. If it bugs you, just make a blank file in it's place.

Running the Preprocessor as admin should tell Windows to trust it going forward. If you're having issues getting the application to auto generate your component list, let me know. It works for me because I compile the application which you can also do since I have the code for that linked in my signature. 

 

I seem to get an index out of range error when I try to "Apply" or "OK" settings. Not sure where since debugging shows combobox to be perfectly fine with size + capacity 1:

Also a small sidenote is that I see a Settings.bat file gets generated for ease of launch, but not one for a corresponding debug .exe, which would be the initial config on a project

[kasool]

Ah nevermind, I see it's because I didn't choose a resolution, as it's not populated by default. However, yes, I also see now I don't have any components showing up in the editor.

[reepblue]

13 hours ago, kasool said:

Ah nevermind, I see it's because I didn't choose a resolution, as it's not populated by default. However, yes, I also see now I don't have any components showing up in the editor.

That's because no components are included in the template. I was writing a few myself, but I got cold feet as I felt like I was telling people how to make their game. 

You can try this component in your project to ensure everything is working correctly.

Also that was an odd bug with the Resolution Combo box but I do plan to overhaul the settings UI to have scrollbars and such.