DarwinsBox - game library bundle

[Danny02]

Hi,

as many of you I have my own “little” framework or bundle of useful stuff lying around. I published it quite some time ago on GitHub and am using it all the time for all my little projects I am doing.

Some of you might remember that i wrote about JOpenCTM here some time ago, which is also in this package.

In the last month or so I wrote a game resource management framework which I want to show you today. Mainly because of this I created this topic but also to show any other thing I will develop in the future within my lib. I have a lot of code lying around and hope to document everything interesting so it can be of help to others.

So back to topic, here is a wiki article I wrote about the resource management stuff: wiki
I hope you like it and post any criticism you have, because I want to know if I’m the only one finding stuff like this useful or not

[Danny02]

I didn’t get as much replies as I hoped, so I did a little example what one can do with my lib:

As I mention in the wiki article you not only can inject resources but also modify them at build time through simple plugins you can write for my system.

So I wrote a little lib which packs images one uses in a game automatically at build time into texture-atlases (borrowed the code from libgdx).

You can find the code here: AutoAtlas
To enable this feature you only have to add the lib to your classpath and enable the UsedResourceProcessor annotation-processor (how to do this with maven is explained in the wiki).

And here a little example of a game entity:

private class Ball {
        @InjectResource(file = "resources/textures/ball.png")
        private TextureAtlasElement normal;
        @InjectResource(file = "resources/textures/ball_glow.png")
        private TextureAtlasElement glow;
        
        public int x, y;
        public boolean isGlowing;

        public void draw(Graphics2D g) {
            g.drawImage(isGlowing ? glow.getSubImage() : normal.getSubImage(), x, y, null);
        }
    }

No extra resource handling code is needed, a texture atlas gets created automatically at build time and is used when you run the game.

here the created atlas:

http://imageshack.us/a/img6/5023/page0j.png

resources/textures/ball_glow.png		atlas/page0.png, 0, 2D, 2, 2, 0, 37, 37
resources/textures/ball.png		atlas/page0.png, 0, 2D, 41, 2, 0, 37, 37

I hope this will give you guys a better idea what this lib is about.

ps: the texture-atlas implementation is not polished as I would liked, hot-reload is missing and no development fallback, but I think it is a good example of what is possible.

[65K]

@Danny02

I didn’t get as much replies as I hoped, so I did a little example what one can do with my lib:

That could be because you did not explain the actual advantage of your annotation based resource system.

[Danny02]

@65K

That could be because you did not explain the actual advantage of your annotation based resource system.

My thoughts on doing things this way and why they would be an advantage were these:

Firstly this is just a lib which handle some resource management stuff, so the features are of course an advantage, because you won’t have to code them yourself. As stated in the wiki the most basic ones are:

• Hot-Reload of resources, so when on develops a game on can change shaders, textures or entity descriptions(when entity properties are defined in xml for example, like attack damage of a mob) while the game is running
• a unified resource factory which is extensional through own simple plugins
• minimizing the code you have to write for loading files to the bare minimum of writing the file-name

Then of course using annotations for this gives some other nice advantages:

• same advantages as other dependency injection stuff, no dependency from resource type -> resource loader (i.e Shader -> ShaderLoader)
• compile time processing of resources through simple plugins, as I did with my example lib AutoAtlas

PS: comments like:
“to complicated for me”,
“don’t understand this black magic”
or
“don’t like annotation, I only code with static functions”

are also much appreciated

[65K]

@Danny02

Then of course using annotations for this gives some other nice advantages:

• same advantages as other dependency injection stuff, no dependency from resource type -> resource loader (i.e Shader -> ShaderLoader)

But in your Ball class example you have a hard coded dependency to concrete resource files, making it impossible to have balls with individual resources or put the class in a library.
When using DI to wire object structures, you can have different setups with the same classes due to external configurations or the use of interfaces.

[matheus23]

@Danny02

PS: comments like:
“to complicated for me”,
“don’t understand this black magic”
or
“don’t like annotation, I only code with static functions”

are also much appreciated

1. Eh… Have to read the source now
2. Oh yeah… It’s really like black magic to me right now. A reason why I don’t use it yet. It’s just… very complicated
3. No I really LOVE annotations. I started with static variables, but I drove cracy later (WorldOfCube was a mess, see github. I changed it to this enum-version, but now I’ve got pretty heavy memory problems…).

It’s a pretty cool Idea, btw.
Also, at first I wondered, whether the hot-reload (which is epic, IMO) gives some kind of callback, when something is reloaded. I know there is something like the ShaderLoader, which will be invoked of course, but what if the ShaderLoader is not in my code base? I haven’t read the source yet, so it’s probably already in there, the callback.

Don’t be too upset that there is not so much comments for something cool like this. It’s just because it’s black magic, and people don’t bother understanding this, since their resource loading methods work like a charm already.

I’m off ready the source now

EDIT: What I also wanted to add: Provide demos. Demos are awesome. Something like a text file previewer. The user can open up the text file and edit it, and will see the change immediately. You can do this with shaders too, but I think not every user, who wants to use your library knows how to use shaders.

[Danny02]

So I updated the wiki page with a lot of links, so you hopefully can better find stuff.

Here a little overview which interfaces can be implemented to use specific features:
basic

• ResourceFrom<Bundle/Handle>: Use this for basic Resource loaders i.e. Shaderloader implements ResourceFromBundle
• ResourceFrom<Bundle/Handle>Provider: these are the factory classes which create the loaders for the system, need to be plugged in with the Java Service Provider system

advance(optional)

• ResourceProcessor: a Java Service Provider plugin which can transform and or create new resources at compile time
• ResourceDependecyInspector: a Java Service Provider plugin which is used to find resource dependecys (like the *.mtl files of a OBJ model)
• ResourceCache: when you want to do some fancy resource caching

@65K

But in your Ball class example you have a hard coded dependency to concrete resource files, making it impossible to have balls with individual resources or put the class in a library.
When using DI to wire object structures, you can have different setups with the same classes due to external configurations or the use of interfaces.

I ment that one don’t have a dependency between a resource and the loading class, these annotations are mainly useful for static resources.

When you want to load dynamic resources, you can get a Resource from the ResourceInjector with the get method(just added it)

[Danny02]

@matheus23

EDIT: What I also wanted to add: Provide demos. Demos are awesome. Something like a text file previewer. The user can open up the text file and edit it, and will see the change immediately. You can do this with shaders too, but I think not every user, who wants to use your library knows how to use shaders.

here you go:Resource Demo
binary download:here

A simple little demo which demonstrates how to write a simple loader and how hot-reloading works.
This demo displays a simple JFrame were a Image is rendered in. When you run the app you can edit the image file and any changes will be displayed on the JFrame in just a few ms.

A quick word where the code is looking for a file.

1. as a normal file in the working directory
2. when devmode is activated also in “./src/main/resources” normal maven resource directory (I could also add some more dev dirs)
3. at last it looks in the classpath, were hot-reload doesn’t work of course

So to test this little demo just run it from within your IDE, go to ./src/main/resources/logo3.png and edit it with your preferred imagee-tool and press save

[matheus23]

Okey. Cool you provided the source on github…

The idea of running an application, which updates an image on-the-fly is also very cool. I really couldn’t wait to run the app…

But a .jar would have been much nicer…
I’ve now at first downloaded the github repository, created a new project in eclipse -> added the source.
So okey. Seems like the resourcehandling sources aren’t included (of course… the shouldn’t be anyways). I donwloaded the DarwinsBox repository as zip. Then added the source from DarwinsBox-master/ResourceHandling/src/main/java and still I’m missing packages like “com.google.inject.Provider” as well as “javax.inject.Singleton”. I searched through all those packages from all your projects in DarwinsBox (Utils, Core, etc.), but couldn’t find the packages, as expected.

I’m am using OpenJDK 7 and really wondering from where these classes come from. And I really would just like to have a .jar, since usually the effort I have put into setting up your demo was already pretty high…

If you don’t want to provide the compiled source, please provide the source with all it’s dependencies (I wouldn’t do this, since you’d need to put stuff into repositories even though they don’t belong there) and provide an ant build.xml or something similar.
What I’d suggest you do is simply provide a .jar we can run with double-click. The least effort for the user, who tries out your demo is the best.
No need to provide the source code in the beginning. The user only checks out your source in case he is impressed by what he has seen. He won’t be impressed by words and code only in the beginning, even if he checks out the source. You simply can’t expect that.

As I said, provide a .jar please, and say me from where you got those cool javax.inject and com.google.inject stuff, I really like the @Singleton stuff

[Danny02]

Hi sry to answer that late, new year and so on

I use maven as the build system, so maven would download all the dependencies you need on build.
To get stuff running from source you would have to first build the DarwinsBox project and then the Demo on.

Netbeans has build in maven support, so when you clone the two repositories from Github you should be able to open them as projects with the normal ‘Open Project’ dialog.

To get a maven build running with eclipse take a look at http://www.eclipse.org/m2e/

So here you go. Please try it, it is really worth your time in my opinion :).
In the zip you will find the ResourceDemo from above, bundled with all needed dependencies.

When you want to try the ResourceHandling lib for yourself just include the same libs as are provided with the demo.

PS: I know that the package is quite big with its 1.4mb , but with something like proguard or jshrink one should get it down too some kb(a lot of unused classes).

PSS:

@matheus23

[…] and say me from where you got those cool javax.inject and com.google.inject stuff, I really like the @Singleton stuff

This is from the Dependency-Injection(DI) frameworks, the javax stuff is a JSR for DI standardization and the google stuff comes from the Guava lib which is a DI framework. When you take a look at the App.java from the Demo you can see how I used Guava in the main.

[matheus23]

So Danny02 has talked to me over IRC and it seemed like the link to the google files was working, but it wasn’t possible to download the zip, because of an infinite redirection loop (^^ experience it yourself ).
It should be mentioned, he already changed the link in his previous post do the dropbox link

So now to the Application / Library:
Very intresting. Amazing actually. I could think of how much this makes your life easier, for example as an Artist.
It could even help me right now: I’ve got a Box2D world set up with LibGDX. I’m using a generated .json file from the PhysicsBodyEditor. If I had hot-reload I could edit the Box2D body at runtime. This would decrease development time a lot. (Full restart means: Reloading of sprites, body .json’s, classes, new window setup, and the world would be reset (bodies at their starting positions))

The demo he has set up is basically this code:
On pastebin.
Basically it’s this, as you already know:
[icode]
@InjectResource(file = “logo3.png”)
private ImageWrapper logo;
[/icode]
and
[icode]
Guice.createInjector(Stage.DEVELOPMENT, new ResourceHandlingModul()).getInstance(App.class).start();
[/icode]
And except for some naming issues (Some german there: “Modul” -> Module ) I find this really amazing.

The result is this:

I opened up the .jar, and next to it I opened up “logo3.png” with GIMP.
When I changed the image in GIMP and pressed Ctrl + E in GIMP, It immediately hot-reloaded the Image in the JFrame. Very cool
I guess I’ll now use this lib

[ctomni231]

How much time does it take between editing the image and the update into JFrame? (I would like to know that before downloading this tool, it could be very useful since my other projects are very heavily “art” based.)

[Danny02]

just give the demo a try ctomni231 :).

Performance of hot-reload:
~100ms(a constant I use) for the system to notice that a file-changed
x ms for your code to load the resource(depending on the filesize and of course your system: hard-disc ect.)
x ms for your complex update code

And remember that all this is happening asynchronous to your normal program in an own thread.

the performance of Injection is of course a bit worse then using a normal constructor, because I use reflektion, but you should code in a way that this doesn’t matter. For example if you want to have a particle which gets created thousands of times per frame you wouldn’t want to inject in each particle object. You instead would want to inject the needed resources into a factory which then can create the needed objects very cheaply.

For example

class ParticleFactory
{
  @InjectResource(file="particleSprite.png")
  Image sprite;

  public Particle create()
  {
    return new Particle(sprite);
  }
}

So the Performance of injection is:
[x ms analyzing the resource class to find fields which needs injection. only the first time the class is used]
x ms make a lookup in the resource cache
[x ms to load the resource, when not present in cache]
x ms to set the fields over reflektion

[Danny02]

little update:

all my libs are now on maven central. They can be found under the groupId “com.github.danny02”

<dependency>
    <groupId>com.github.danny02</groupId>
    <artifactId>[...]</artifactId>
    <version>2.1</version>
</dependency>

ps: after some try&error setting things up to be pushed to central was quite easy, so if anybody of you needs help with that, I would be happy to help.