Example applications

[czyzby]

• Simple gdx-setup project templates.
  • KTX projects can be generated with unofficial gdx-setup and gdx-liftoff.
• Wiki with a simple game tutorial.
  • KTX tutorial with a simple game can be found here.
• A separate repository with simple project setup examples.
  • @jojomickymack demos showcase various setups and use many KTX modules.
• Create a wiki page with contributed tutorials and example projects.
  • Project wiki now lists useful resources.
• A more advanced game example showcasing multiple KTX modules.
  • @Quillraven's Adventure game and Dark Matter are some good examples.

---

See also czyzby/gdx-setup#38.

[czyzby]

While the library was aimed at LibGDX users that want to improve their development experience with Kotlin, one could certainly start with KTX and Kotlin altogether. The documentation is extensive (I hope), but it does require prior LibGDX knowledge - it lacks simple game examples that could take you through the beginning. This should be our first priority right now.

[Tibi]

Just sayin', but I'm learning LibGDX and Kotlin... and I'm using bialjam17 as an example application.
So if I contract bad habits, I'll blame you ;-)

Seriously, yes the KTX doc is really good, but it would be awesome to have a "canonical" application that shows the state of the art way to do things with KTX.

[czyzby]

@Tibi I'm fully aware of that, but I just don't have that much time for open source/gamedev lately. I wouldn't mind some contributions that I could just review (and potentially refactor) before making them official examples. Maintaining the project is one thing, but actively creating a decent tutorial + example code requires quite a bit of time.

As far as my game jams projects go, bialjam17 is definitely not the worst one. I think it uses a pretty recent KTX version without any major differences between the latest one. While I'd definitely refactor a lot of stuff - like anything hardcoded or using fixed positions - it's still better than nothing. Let me know if you have any questions about general LibGDX/KTX stuff - you can even create a separate issue for that.

[aouerf]

Are you thinking of something similar to this but using KTX for the most part? I also agree that the documentation for each module is great and can be put in the wiki as-is.

[czyzby]

@aouerfelli I wanted to avoid putting the documentation in the wiki instead of README files, as it's easy for the wiki to go out of sync. In case of any pull requests to the main repo, I can just bug people to update the CHANGELOG and all README files in the same request - GitHub wikis are separate repositories, so it wouldn't be that easy.

About the example project - I wanted to start with a simple game (Flappy Bird clone?) using techniques close to the original LibGDX, and gradually rewrite each part to idiomatic Kotlin with KTX. E.g. initially loading assets manually, then via AssetManager with KTX extensions, then with async AssetStorage. Something like the simple game would be a great starting point and I'd be happy to review the code if you want to help, but eventually it would be nice to showcase each module in practice.

[czyzby]

Looks like someone made a tutorial. :)

[abueide]

Is there any tutorial showing how exactly i'm supposed to use AssetStorage with ktx-async inside my game properly?

[czyzby]

I'm afraid the ktx-async guide is the best you've got, @abueide. AssetStorage is more or less a drop-in replacement for AssetManager. Pre-load the assets that you need initially, load extra assets as required. The only difference is that AssetManager forces you to wait for the asset to get a reference to it, while AssetStorage hides the async loading complexity thanks to coroutines.

[abueide]

@czyzby Sorry for the barrage of questions.

1. Is it generally bad practice to load every asset on startup recursively? if so then what is the point of using AssetStorage? Is it so the initial assets you load can load faster by using multiple threads?

2. Should I load assets on a Screen by Screen basis? Like if your going into a forest dungeon unload all the current assets and load the forest level's assets?

3. Is this the number of threads your using to load the assets? asynchronousExecutorConcurrencyLevel = 1. If so how many threads should I allocate? Should I do it dynamically depending on how many threads the machine has?

4. Do I have to do anything special to make the assets load asynchronously other than whats shown in the tutorial?

[czyzby]

1. If you're 100% sure the assets can fit in memory, you can load all of them at once. Even if you load all assets immediately on startup, AssetManager/AssetStorage make it easier to pass them around, dispose of them, and so on. It's also much easier to refactor your app to load some assets on demand later if you use a manager rather than load each asset manually. About the threading model: afaik, AssetManager uses only 1 extra thread. AssetStorage uses as many threads as you choose during KtxAsync initiation, but it still has to perform some OpenGL operations on the main rendering thread.

2. Sounds reasonable. Unless you change levels very often and pre-loading some extra assets makes sense.

3. Depends on how much async operations you're planning on performing. Remember than only some I/O operations can be performed asynchronously, and some assets are still mostly loaded on the rendering thread (e.g. textures). If you use KtxAsync extensively outside of asset loading, using more threads is reasonable. Otherwise they'll just stay idle.

4. Using AssetManager/AssetStorage is enough. They basically ask AsynchronousAssetLoader implementations specific to asset class to handle the loading. If the loader is properly implemented and does most of the work asynchronously, you're good to go. You can check official loader implementations, or even try implementing your own and print current threads to make sure it works properly.

[abueide]

@czyzby Thank you, you answered my questions perfectly I appreciate it :)

[czyzby]

@abueide Feel free to create new issues with more questions if anything else comes up. ;)

[jojomickymack]

@czyzby I set up the website with the tutorial you linked to in a message in this thread - now I feel bad I let the domain expire. I just put the content back up on a different site.

https://jojomickymack.gitlab.io/reverie/post/libktx_platformer

If anyone is looking for a starter project, I had created this single scene template a long time ago and I continue to use it as a way to start from scratch without having to mess around with the build files or anything else - others who might be coming across ktx for the first time might be looking for something like this to just get up and running where they can start animating and seeing things working.

https://github.com/jojomickymack/ktxtemplate001

Here's a version of the ktxtemplate with an on screen gamepad and physical gamepad support - a handy drop in input module.

https://github.com/jojomickymack/on_screen_gamepad01

I wrote another article as a sort of starter project for using ashley, the entity component framework.

https://jojomickymack.gitlab.io/reverie/post/ashley_ecs

again, there's an example project that goes with that.

https://github.com/jojomickymack/libgdx_ashley001

If you are interested in the markdown for any of those articles, they are here. Thanks! As you can tell I'm really enthusiastic about the library, I've made some more sophisticated games using it now and I'm constantly discovering more great features in ktx!

[czyzby]

@jojomickymack Thanks, I updated the comment.

I wrote another article as a sort of starter project for using ashley

Have you tried using ktx-ashley?

I've made some more sophisticated games using it now

Would you like to add anything to the showcase?

[jojomickymack]

Wow, I should really adapt my example and the games I made using ashley to use ktx-ashley - I'll make a point of that - there's a ton of features I need to use, like texture packing and the scene2d dsl as mentioned previously - probably can adapt some of these other examples to use those easily.

These examples all use scene2d ktx extensions (no skin builders, texture-packers or dependency injectors). I added a refactored version of the ashley example to use ktx-ashley - it's really nice!

https://github.com/jojomickymack/dialog_adventure
https://github.com/jojomickymack/walker_example
https://github.com/jojomickymack/box2d_tiledmap
https://github.com/jojomickymack/missing-homework
https://github.com/jojomickymack/platform-boy
https://github.com/jojomickymack/alien-cutscene

ktx ashley platformer example
https://github.com/jojomickymack/libktx_ashley01

Here are some other projects I created within the last several months - I doubt any are showcase material but I should make it a personal goal to extend my best one, the dialog-adventure, to be a complete game so it might be worthy of showcasing.

I was inspired that you linked to my tutorial, I should continue working on my games - maybe these examples/templates might help other people somehow if they can find them.

edit - ktx-ashley is really really nice. I was able to refactor some repetitive code where I'm adding components to entities and then adding the entities to the engine with this, much nicer code! Even without knowing much about the rest of the project, it's pretty clear that there's 2 entities, one ai-controlled and one user-controlled that each have a texture and different physics.

var ashleyEngine = Engine()

with(ashleyEngine) {
    addSystem(PhysicsSystem())
    addSystem(RenderSystem())
    addSystem(UserControlledSystem())
    addSystem(AiControlledSystem())
    addSystem(CameraFollowSystem())
}

ashleyEngine.add {
    entity {
        with<TextureComponent> {
            region = TextureRegion(Texture(Gdx.files.internal("alex.png")))
        }
        with<PhysicsComponent> {
            w = 30f
            h = 50f
            pos.set(200f, 200f)
        }
        with<UserControlledComponent> {}
        with<CameraFollowComponent> {}
    }
    entity {
        with<TextureComponent> {
            region = TextureRegion(Texture(Gdx.files.internal("enemy.png")))
        }
        with<PhysicsComponent> {
            w = 40f
            h = 40f
            topSpeed = 100f
            pos.set(100f, 200f)
        }
        with<AiControlledComponent> {}
    }
}

Ktx is filled with nice stuff like this, I also didn't realize that I could queue up Actions to make a "scene" like this. Really great stuff.

var label = Label("Welcome To The Game", AppObj.skin, "default")
label += sequence(delay(2f) + fadeIn(2f)) + delay(2f) + fadeOut(2f)

and then add the label to the stage with the same += syntax

stage += label

I think I'm going to try to consolidate these examples into a single app where you select an example and it's loaded into a screen, that way I don't have dozens of repositories with one example each.

You know I always meant to use the actual extensions more and haven't until now - really great stuff!

[czyzby]

@Quillraven Good job! I had a quick look at it and it looks good so far, I'll read through the whole thing this week. I don't mind linking your wiki in this repository.

[jojomickymack]

There are a bunch of 'graphics demos' I consolidated into this ktx-demos app - it's a hodge podge of shader demos I refactored to kotlin from mattdesl's tutorials and some other sources.

This is some pretty advanced opengl stuff and working with it is a learning experience. I'm planning on adding more stuff highlighting ktx features as I keep going, but since the app is in a working state I wanted to throw it on here with the other links. I know it's buggy and not very original, still, the effects are really cool and they're all tweakable.

[czyzby]

@Quillraven I'll go ahead and link your tutorial in the repo's wiki. Thanks for the contribution!
@jojomickymack Same goes for your repositories. If you'd like to list them in a different manner, please update the wiki.

[czyzby]

@jojomickymack Would you mind adding tags to your blog posts or some way to filter the posts that mention KTX? I'd like to link your blog as well, if you're OK with this.

[Quillraven]

Glad I could help :)

I have a question though and sorry if this is the wrong place for it.
I am currently also using scene2d, freetype and assets extensions in one of my projects and I am not 100% sure if I am doing it correctly because somehow it feels strange.

I create my skin like this:

private fun createSkin(assets: AssetManager): Skin {
        // create fonts that are referenced in skin's json file
        // and store them in a map to pass them as resource dependencies for the skin
        val skinResources = ObjectMap<String, Any>()
        val fontGenerator by assets.loadOnDemand<FreeTypeFontGenerator>("ui/8-bit.ttf")
        skinResources.put("font_default", fontGenerator.generateFont { size = 32 })
        skinResources.put("font_huge", fontGenerator.generateFont { size = 64 })
        // unload the generator as it is no longer needed
        assets.unload("ui/8-bit.ttf")
        return assets.loadOnDemand<Skin>("ui/ui.json", SkinLoader.SkinParameter(skinResources)).asset
    }

The "loadFreeTypeFont" method always returned the same asset for some reason so I changed it to this version where I am using a generator. Also, "freeTypeFontParameter" cannot be used for "generateFont" because it is a LoaderParameter and not a "normal" parameter. Is this correct? Is there an easier/better way to do it? My skin json file is using "font_default" and "font_huge" as font values and therefore I need to create them before loading the skin and passing them as dependencies.

When disposing the assetmanager I get a "Pixmap already disposed" exception. From what I can tell this seems to be a bug because the font dependency for the skin is not correctly handled and therefore the skin is disposing them and also the assetmanager.
What I did is the following (note that my assetmanager is part of the context):

 override fun dispose() {
        // remove bitmap fonts from skin because they are loaded via assetmanager and he will take
        // care of the disposal. Otherwise they get disposed twice and we get an "Pixmap already disposed" exception
        val skin = context.inject<Skin>()
        for (fontKey in skin.getAll(BitmapFont::class.java).keys()) {
            skin.remove(fontKey, BitmapFont::class.java)
        }
        context.dispose()
        super.dispose()
    }

Again, is there a better way to do it? And if not, maybe we could add something to freetype extension to automatically do this stuff before disposing the assetmanager?

And thank you again for these great extensions. I really learned a lot from it and I have a lot of fun learning and using them in my projects :)

[jojomickymack]

@czyzby I just made some changes to my blog to make the whole thing ktx exclusive - I changed the title of the blog to 'ktx-reverie' - I probably shouldn't change the name of the url though (it would invalidate previously used links).

I also just wanted to note that the repo for the site is public, meaning that anyone can do a merge request and I will approve it. The site is made using hugo - so it's really low maintenance - anyone can contribute, not just me.

Having revisited that site makes me feel that it needs some improvements (pictures, more articles, etc), so I'll be updating it/enhancing it periodically.

I'd like to do a short series of physics demos similar to the nature of code using your excellent box2d extensions.

[czyzby]

@jojomickymack Wow, that's great! Looking forward to the physics demo. I linked the blog on the wiki, thanks.

@Quillraven

I have a question though and sorry if this is the wrong place for it.

When in doubt, you can always create a second issue. It's OK to create issues with questions about the project.

The "loadFreeTypeFont" method always returned the same asset for some reason so I changed it to this version where I am using a generator.

This is because in LibGDX AssetManager assets are uniquely identified by their path (and type?), so you're probably better off using the generate method.

Also, "freeTypeFontParameter" cannot be used for "generateFont" because it is a LoaderParameter and not a "normal" parameter. Is this correct?

Well, it comes down to a simple Java object, so there could be a utility method similar to loadFreeTypeFont that takes a free type FreeTypeFontParameter, but it's simply less convenient and something you can already do with a simple generic load that works with most assets. loadFreeTypeFont is essentially a building API for FreeTypeFontParameter.

Is there an easier/better way to do it? My skin json file is using "font_default" and "font_huge" as font values and therefore I need to create them before loading the skin and passing them as dependencies.

I'm a bit biased, but I'd use ktx-style builders instead of non-type-safe ui.json file to load the skin. You can create a Skin programmatically with Kotlin-style builders API. You'd have a better control over when the assets are loaded.

When disposing the assetmanager I get a "Pixmap already disposed" exception. From what I can tell this seems to be a bug because the font dependency for the skin is not correctly handled and therefore the skin is disposing them and also the assetmanager.

If you look at the freetype extension file, it all comes down to syntax sugar. It just adds the official loaders and makes it easier to use them to load fonts. If disposing of the assets causes an exception, it is because the official loaders fail to increase the asset reference count in the first place.

Again, I'd give ktx-style a chance, since then the Skin won't be managed by the AssetManager and you should avoid the disposing issues.

[jojomickymack]

@czyzby I've shaped up this ktx demos repo quite a bit with some box2d and ktx specific graphics and scene2d stuff and it continues to grow. It's intended to be run on Android with a RecyclerView menu, but there's a desktop launcher with a minimal menu for selecting demos for desktop development/debugging. Once it gets to a certain size I'd like to put it up in the play store for free.

If anybody on github feels like adding additional screens to this, I'll merge any pull requests!

One thing I wanted to mention since I was just adding the 'use' extension for all my batches and shaders - another possible feature might be to have the same 'use' extension extend to FrameBuffer since they too have begin() and end() wrapping calls (usually containing draw calls for a batch - which would result in nested 'use' blocks).

You can see an example of how framebuffers are typically used in mattdesl's wiki - I wonder if nesting 'use' blocks would cause problems?

Anyway, just wanted to relay that feature idea to you since batches and shaders have 'use' extensions but FrameBuffers don't yet and it seems like they could to blend in with the others.

[czyzby]

another possible feature might be to have the same 'use' extension extend to FrameBuffer since they too have begin() and end() wrapping calls

Good idea. I don't see why we wouldn't support most of these, although LibGDX APIs do not support a common interface for classes with begin/end methods, so we have to add them one by one manually. Would you like to create a pull request? #200

[jojomickymack]

@czyzby Hey, sorry this is kind of turning into a q and a thread - I'm going through my examples and changing all the lines below in my render methods from

Gdx.gl.glClearColor(0.6f, 0.6f, 0.6f, 1f)
Gdx.gl.glClear(GL20.GL_COLOR_BUFFER_BIT or GL20.GL_DEPTH_BUFFER_BIT)

to

clearScreen(0.6f, 0.6f, 0.6f). 

clearScreen does the same thing with all examples except for those that use models, ie this model example and I found that the model doesn't render with clearScreen.

The ktx clearScreen method only clears the buffer bit - the 'or GL20.GL_DEPTH_BUFFER_BIT' part is missing, which is the only difference from what I normally put there.

I started doing that probably because it's stated in the libgdx wiki to have the depth buffer bit part - honestly I don't understand when or why it might clear one or the other, but it seems to make a big difference when rendering models.

I was checking on xoppa's most basic 3d example, and the 'or GL20.GL_DEPTH_BUFFER_BIT' is definitely there and removing it results in the model not being rendered.

I wonder if ktx should have 'or GL20.GL_DEPTH_BUFFER_BIT' added in the 'clearScreen' method? I'm not sure if there's any drawbacks to it - I've been using it for all 3d and 2d stuff for as long as I can remember.

[czyzby]

@jojomickymack Sounds reasonable, could you submit a PR?

[jojomickymack]

@czyzby Here's that #202 - I did the pull request to master, let me know if I should've done the pull request to the dev branch. I modified the unit test so it passes with the change.

[jojomickymack]

@czyzby did a new PR branching off the develop branch this time #203

[czyzby]

Latest develop changes include a rewrite of the main README.md file, which now has some Gradle setup examples. This should make it a bit easier to get started with KTX.

[czyzby]

@Quillraven created a YouTube series explaining various parts of the framework. I think this series combined with the tutorial and other KTX resources is enough to get started.