LibGDX architecture design guidelines

From my experiences, there is no standard everyone is following. libGDX developers come from different backgrounds. Some are backend developers in their day life, some are just hobbyist devs and learn their first development skills.

I see a lot of libGDX open-sourced projects with typical static SomeManager.getInstance() calls, while I prefer to pass-through references (as a backend developer, you will know about the advantages - testability and so on).

Even the libGDX backend itself does not follow one single approach. There are some parts getting references to managers by reflection (which is not good, because you must exclude such classes from obfusciation) and some using static getInstances().

If you also HTML5, you also must respect some GWT-based restrictions, so you are sometimes forced to go a way you would never do when developing Spring Boot applications.

Now that 3 years passed I can answer this question myself.

I found that using ECS (Entity-Component-System) is the best approach for creating games.

With this approach you'll have 3 different purpose objects. As name suggests they are:

• Entity - is just a general purpose object which only contains set of component objects, and usually an ID.
• Component - is a bag of data. No logic just plain POJO. The data it contains will define the behaviour of Entity which contains the component.
• System - is where you put your logic. Every system should process an entity if and only if it contains a very specific set of components.
• Engine - is a representation of a scene where all entities live, and are processed by systems.

The easies way of implementing such approach is by using Ashley lib. It's a lightweight implementation of ECS. Although as my experience has shown this works best in a case of real gameplay. If you want to have very specific animations (even of game objects) then use scene2d.

Scene2d represents a more familiar (to vast majority of developers) approach. It's a graph of UI elements which are placed in a hierarchy. There are very useful Actions which can be used to implement your animations. It also works best for any UI that you want to display in your game.

So to sum it all up I have worked out that you should have a couple of classes per screen to have a distinct division of labour.

• Screen - I see it as a branch of running code. It contains an Engine (if we need an ECS) and a Stage (if we need an UI). Handles all game events, user input and routing.
• Engine - ecs container which knows how to manage its systems, entities and components.
• Stage - UI container which knows what UI elements should be present, how they should look and behave.

Simple example in kotlin (NOTE in my real project I use koin DI to bind all together):

class MyGameScreen : Screen, MyGameEngine.Callback, MyGameStage.Callback {

    val engine = MyGameEngine(callback = this)
    val stage = MyGameStage(callback = this)

    override fun create() {
        engine.create()
        stage.create()
    }

    override fun render(delta: Float) {
        enigne.update(delta)
        stage.act(delta)
        stage.draw()
    }

    override fun dispose() {
        enigne.dispose()
        stage.dispose()
    }

    override fun buttonPress() {
        //handle button press
    }

    override fun onGameEvent(event: MyGameEngine.Event) {
        //handle some game event
    }

}

class MyGameEngine(
    private val callback: Callback
) : com.badlogic.ashley.core.PooledEngine() {

    fun create() {
        // create and add all your systems and entities
    }

    sealed class Event {
        // ...
    }

    interface Callback {
        fun onGameEvent(event: Event)
    }

}

class MyGameStage(
    private val callback: Callback
) : com.badlogic.gdx.scenes.scene2d.Stage() {

    val button1 = TextButton(...).apply {
        addClickListener { callback.buttonPress() }
    }
    
    val label1 = Label(...)

    // and so on

    fun create() {
        val root = Table().apply {
            // add all your actors to the root table
        }

        val rootContainer = Container(root).apply {
            setFillParent(true)
            fill()
            top()
        }

        addActor(rootContainer)
    }

    fun startSomeAnimation() {
        val action = Actions.sequence(
            // your animation
        )

        addAction(action)
    }

    interface Callback {
        fun buttonPress()
    }

}