Rebirth - Game Resources Library

Rebirth is a resource system designed for games, which makes it fast and easy to make your game data driven without having to write lots of tedious boilerplate parsing code. It’s also a full resource manager, and handles object lifetimes and background loading in a seperate thread. And for maximum productivity it monitors your file system for file modifications and automatically reloads the affected resources while your game is still running.

Current version
Rebirth library jar
Browsable Javadoc
Test results

Getting started
Check out the quick start guide and quick start part two.

About
The resource system is heavily inspired by Cas’ resource system from SPGL, which I’ve been using for a while. The gist is to use copious amounts of reflection to convert from xml to a Java object based on the field names and types. Cas’ system is pretty good, but it’s starting to show it’s age and there was a bunch of things I wanted to improve or add. The big improvements are:

  • background loading
  • cleaner xml syntax
  • pluggable decoders for user and 3rd party types
  • auto reload for modified files
  • resource inheritance

I’m pretty much calling this version 1.0, as it’s complete and has all the core functionality you should need. Documentation is a little sparse but I’m working on that at the moment (feedback appreciated). Error handling should be robust but errors might be a little confusing to a beginner so suggestions for improvements there are appreciated too.

License is pending, but will probably be MIT or BSD unless anyone has any strong arguments against one of these.

So there you go. :slight_smile: Comments and feedback of any kind greatly appreciated, and if you try it and hit any problems then post here or find me in #lwjgl.

Shweeeet! I’ll take a peek at it. Getting a bit sick of the foibles in my code.

Cas :slight_smile:

Looks cool, great idea. That would make it a lot easier to change things for graphics and balancing.

It’s such a pity that java’s security is all or nothing, so reflection requires an ‘all permissions’ security dialog.

Only access out of scope - the library could be tweaked to only work with public members. I suppose it’d be a bit less useful then.

Cas :slight_smile:

Hmm, I always end up requesting all-permissions anyway, so I hadn’t thought about that. Certainly accessing and setting private members is by design (because if you’re obsessive like me you make your automatically parsed members private and write accessors for them so resources are properly immutable), but if you’re careful to only read from them there’s nothing stopping you working with all public fields.

I’ll have to look into the reflection security stuff, it’s entirely possible that it’s usable without permissions in it’s current state (although you might have to tag private members with @NonParsable so they get skipped).

That’s interesting, hadn’t thought about just changing public members.

Don’t go to any trouble trying to fix it, I was just thinking out loud about how annoying reflection is like that.

Cool library 8)

Seems neat! I like the idea of just putting stuff in a directory and then getting a reference to it and using it. Can it do more than parse XML? How about YAML? What if it could load images?

If you used something like XStream for XML or, even better ;), YamlBeans for YAML, those libs serialize and deserialize object graphs without the need for a decoder, or even objects in the graph to extend a class.

Stepping back from Rebirth a bit and just thinking about what I’d like to see in a resource management system:

  • Progress is important. Probably less so with configuration files, since they probably parse quickly, but loading images, maybe building a database, etc. Should be a nice way to get a percentage of progress. If the framework has many tasks and some of them don’t have an idea of completion percentage, then the progress percentage would be indeterminate. However, and this is the clever bit ;), what if it remembered the time it took, so next time the app runs it will show progress percentage based on time.
  • Easy of use. Serialized objects shouldn’t have to extend a class. The framework shouldn’t require any setup, just files in a directory and some Java code to create a resource pool.
  • Adding resource types should be easy. Eg, what if I wanted .sql files to be run in an in-memory database using the resource system in order to gain progress status and file watching? What if I wanted to do image loading via LWJGL? Via Slick? Audio loading?
  • What happens if all my resources are in JARs? Might be neat to work from the file system, classpath, JAR, ZIP, URL, etc. Might want to make how the resources are found and loaded very flexible to support this sort of thing.
  • Might be nice to clear a resource pool. Imagine you had separate game screens that were very resource intensive. When you leave a screen you could clear its resources and when you show a screen you would load them again. Would be sweet if this were just a method call or two. Resources could be treated generically and have a lifecycle, so different resource types would have hooks to init/destroy/whatever.
  • How about a way to save resources? My config files can usually be changed in-game and are written back to disk. Maybe resources could even be added to a resource pool programmatically and it would create new files.
  • Background loading should be cancelable. Eg, if something is loading in the background and the user leaves that screen, the loading should stop.

(with apologies about the length…)

XML only at the moment - I’ve never actually seen YAML used “in the wild” myself, I suppose it could be added but I see it making the API more complicated and harder to use with little benifit.

[quote]If you used something like XStream for XML or, even better ;), YamlBeans for YAML, those libs serialize and deserialize object graphs without the need for a decoder, or even objects in the graph to extend a class.
[/quote]
I looked at using XStream but it wasn’t a great fit. XStream aims to just convert to/from xml with as little effort as possible - Rebirth is about making your own xml syntax for resources and converting that into a set of objects with minimal parsing code. Obviously I’ve pinched the handy bits (like auto decoding of primative and array types) anyway so adding XStream as well doesn’t make sense.

[quote]Progress is important. Probably less so with configuration files, since they probably parse quickly, but loading images, maybe building a database, etc. Should be a nice way to get a percentage of progress. If the framework has many tasks and some of them don’t have an idea of completion percentage, then the progress percentage would be indeterminate. However, and this is the clever bit ;), what if it remembered the time it took, so next time the app runs it will show progress percentage based on time.
[/quote]
It’s already possible to determine loading progress over the top of the current system by looking at resource states. I plan on writing a better ‘resource phase’ system over the top for typical per-level style resource management which will have progress tracking.

[quote]Easy of use. Serialized objects shouldn’t have to extend a class. The framework shouldn’t require any setup, just files in a directory and some Java code to create a resource pool.
[/quote]
Rebirth resources don’t have to extend a base class, but they do need to implement an interface so they can have their lifecycle managed. Trivial resources (which just use auto parsing) can extend a base class to get that behaviour ‘for free’. For classes you can’t control or implement an interface then Decoders let you use these easily.

[quote]Adding resource types should be easy. Eg, what if I wanted .sql files to be run in an in-memory database using the resource system in order to gain progress status and file watching? What if I wanted to do image loading via LWJGL? Via Slick? Audio loading?
[/quote]
The Rebirth approach to this is that you use your regular image/db/audio resources, and have a Resource which creates them in the create() callback. Main-thread callbacks let you do any initialisation which has to happen in the main thread (like texture uploads).

[quote]What happens if all my resources are in JARs? Might be neat to work from the file system, classpath, JAR, ZIP, URL, etc. Might want to make how the resources are found and loaded very flexible to support this sort of thing.
[/quote]
Native file system (for development) and jars (for deployment) are supported out-of-the-box. If you want to support additional locations like zip or over the internet then the ResourceIO interface lets you do that.

[quote]Might be nice to clear a resource pool. Imagine you had separate game screens that were very resource intensive. When you leave a screen you could clear its resources and when you show a screen you would load them again. Would be sweet if this were just a method call or two. Resources could be treated generically and have a lifecycle, so different resource types would have hooks to init/destroy/whatever.
[/quote]
See above comments on progress tracking.

[quote]How about a way to save resources? My config files can usually be changed in-game and are written back to disk. Maybe resources could even be added to a resource pool programmatically and it would create new files.
[/quote]
Config files and any savable state/progress isn’t part of a resource system IMHO. Resources are very deliberately immutable, intended to be in a jar or on read-only media (CD/DVD). More of a job for something like XStream IMHO.

I think I should emphasise that Rebirth is not XStream. They solve different problems in entirely different ways. I really would suggest giving it a try rather than picking apart the feature list - it’s only a couple of function calls to get started and you’ll quickly see easy it is to add and tweek resources. Plus, I’m much more likely to add/change things if you’re using it rather than armchair debating it. :wink:

Did you take a look at JAXB? If so, why did you abadon it (for your XML->Object conversion part). I am just curious.

I had a look at quite a few xml apis when I started writing this, but I can’t remember if I looked at jaxb specifically. Personally I’m really not a fan of xml schema files (big, verbose, tedious) and the whole idea of the library is that it’s easy to use - requiring people know how to create valid schema files and generate code via the jaxb schema compiler is significant extra work I think for minimal added benefit.

My point was, an interface doesn’t seem necessary for POJOs/beans, and Decoders don’t seem necessary for 3rd party POJOs/beans.

[quote]The Rebirth approach to this is that you use your regular image/db/audio resources, and have a Resource which creates them in the create() callback. Main-thread callbacks let you do any initialisation which has to happen in the main thread (like texture uploads).
[/quote]
I liked the idea of automating it, of only needing to ask for a reference.

[quote]I really would suggest giving it a try rather than picking apart the feature list - it’s only a couple of function calls to get started and you’ll quickly see easy it is to add and tweek resources. Plus, I’m much more likely to add/change things if you’re using it rather than armchair debating it. :wink:
[/quote]
Well, you asked for feedback and comments. :slight_smile: I have a strong distaste for hand editing XML, but mostly I don’t currently have any projects with enough configuration to warrant Rebirth.

You can just annotate a java class and you are done. Unfortunately that’s exactly the part of JAXB that isn’t well visible in the myriads of schema centric articles about it :confused: You can even do the opposite and generate a schema from the annotated classes to get code-completion in xml editors / ides.

Sounds promising. I’ll look into it but I’m not convinced it’s not too “enterprisey” for my usage.

Decoders allow you to do a lot more though - like defining custom syntax instead of a straight one to one mapping of attributes to members. For example a Color decoder could let you define one as “red=10 blue=20 green=30”, or “light blue” or “0xAA99DD”, or “(0.4, 0.6, 0.1)”. And if you provide a decoder for your native texture/image/etc. then it will be automated in your resource class.

There’s a new version up (same urls as before). You can now use it in ‘restrictive’ mode, for use in applets and other sandboxed environments. This works as before with the caveat that resources need to have public members rather than private ones.

Also fixed a few embarassing resource creation and threading bugs, plus added the ability to do a background create of all resources in one go.