Game Configuration

Configuring your Game

Basic Configuration

Configuring the game at start up is quite simple, you simply need to call Game.configure() as follows:

Game.configure {
    setViewport(height = 10.0)
}

Configuring the Game calls Game.start() if it has not been called already. Game.start() simply runs the specified configuration and creates a context. Game.run() should then be called to actually create the Game loop and run the game. Since Game.start() is called automatically, Game.configure() and Game.run() are the only functions that you need to worry about

Note: The .configure() function is an extension function. Behind the scenes, it is calling Game.configureAs(DesktopApplication()) { }. Hopefully, in the future there will be Game.configureAs(AndroidApplication()) or Game.configureAs(WebApplication()) but for now just the DesktopApplication is supported.

Full Configuration

Most of the time the default values should be sufficient, especially for a Hello, World program.

Here as an example of the full extent of configuration:

Game.configure {
    initialize = false // Setting initialize to false means that you have to call Game.start() yourself
    setResolution(1920, 1080)
    setFullscreen(true)
    setViewport(height = 10.0) // it is best to set either the width or the height of the viewport but not both, this will maintain the aspect ratio
    setViewLocation(3.0, 4.0)
    setStartingScene(MyStartingScene())
    setMultisampling(8)

    configureWindow {
        title = "My Game"
        isDecorated = false
    }

    configureDebugMode {
        screenLog = true
        printWarnings = true
    }

    configureProjectionMatrix {
        setPerspective(fov, aspectRatio, nearPlane, farPlane, false)
    }

    setDeltaTimeCalculator(DeltaCalculator.basicConstantCalculator(60.0))

}

Some of the above are fairly self explanatory such as setResolution(1920, 1080) and setMultisampling(8), some of the other should be explained:

• setViewport(height = 10.0)

  The viewport describes the coordinate space that you will be working in, the above says that the height of our window should be 10 units high despite whatever resolution has been set.

  Note: This height value can be changed while the game is running and it will have the effect of zooming out or zooming in. Only the height for the WorldView can be changed, the height and width of the UIView is immutable and it is set once during configuration.

  This function takes 2 parameters, the width and the height, however, only one of the parameters should be set. the other parameter will be automatically assigned based on the aspect ratio of the resolution. So in the example above the height will be set to 10.0, the resolution (1080x1920) will be used to calculate the width. In this example it would be 10.0*(1920/1080) which is the same as 10.0*(16.0/9.0) where 16/9 is our aspect ratio, this comes out with a width of 17.777.

• setFullscreen(true)

  Although the purpose of this function may seem obvious, there are a few things to note about it. Often one might want to make the distinction between a "borderless" window and an ordinary fullscreen window. To create a borderless fullscreen window then the game's resolution should not be set and only setFullscreen(true). This will make the window fullscreen without changing the monitor's video mode. On the other hand, setting the resolution and then setting the window to be fullscreen will change the monitor's video mode to be the specified resolution and will therefor not be borderless

• setStartingScene(MyStartingScene())

  This sets the very first Scene that the game should run, in this case it is a Scene called 'MyStartingScene'. You can learn more about scenes in the Scenes and Processes section

• configureWindow

  This is where the window object can be set and configured. This window object is wrapping an instance of a GLFW Window. Most of the variables in this window object set a corresponding variable in the GLFW Window object. Details about GLFW Windows can be found here.

  For example, isMaximized = true will call glfwMaximizeWindow(window) in GLFW.

• configureDebugMode

  This allows you to set some options that you only want to occur during debugging. There is a list of booleans that can be set and later referred to. The booleans that can be set are:

  • failEarly: tells the game to throw an exception if something is worng rather than trying to salvage the situation
  • printWarnings: prints certain warnings to the console that might be useful
  • screenLog: Shows text on screen for debugging. Use ScreenLog { "This will appear on screen if screenLog is true" } to make use of the screen log
  • constructionDraws: Shows circles and rectangles on the screen if needed. Use something like DebugDraw.drawCircle(vec(0, 0), 0.5) to draw a circle on the screen that will only appear when constructionDraws is set to true

• configureProjectionMatrix

  Set how the projection matrix should be configured. By default it is set to be a perspective matrix, however it could also be set to be a orthographic matrix if desired. The matrix being configured is a Matrix4f objecct from JOML and details of which can be found here

• setDeltaTimeCalculator(calculator: DeltaCalculator)

  This takes an instance of DeltaCalculator and it is for calculating the time between frames in custom ways. There are various in built implementations in the companion object of DeltaCalculator such as DeltaCalculator.basicVariableCalculator()