

= Cubes - A Block World Framework


image::http///destroflyer.mania-community.de/other/imagehost/cubes/header.png[header.png,with="650",height="",align="center"]



*work-in-progress*


As the title says, “Cubes is a framework for block worlds (also called “bloxel or “minecraft-like) - It offers an easy way to add/remove blocks, block skinning, useful tools and user-specific behaviours. “Cubes itself will not contain tools for creating crafting or RPG functionalities, it will *only* help you managing the block system.



== The origin

In the summer of 2011, I (destroflyer) started a little minecraft clone (like almost every jMonkey) - nothing special, I just wanted a little block world in which players can walk around, place or remove blocks and the ability to save those maps. It didn't take long until I stumbled across the “batch-boxes-to-improve-performance, texture atlas and mesh optimization things - Luckily, I managed to get those to run, played a few rounds with a friend and that was it. The code was really quick 'n dirty and at this time, my studies at the university began. The “game was never started anymore and was hidden in the jME-projects folder - Until a few days ago.


Almost every two days, a new thread in the forum appears, where people talk about “bloxel worlds, mesh optimization, batching and so on… As the discussions about the +++<abbr title="Graphical User Interface">GUI</abbr>+++ frameworks (Nifty and its upcoming alternatives) began, I thought: “Why don't you create a block-world-framework, that the people can use easily? :)


I read my old code (mainly the chunk management and the mesh optimizer) again and started to code the named framework from scratch - After a few hours, I made the block world run and after 2 days it seemed to work in the way I like it to work.


At the moment, the “block engine includes all necessary features for a minecraft-like world and even a few useful tools (e.g. loading blocks from heightmaps, noises, …) - Time to publish a first preview. :)



== How it works

The vertex buffers, UV coordinates, chunk management, block faces, … … … … nah, just kidding. :P I think, everyone who knows about this topic, knows how bloxel-engines work. And in case you don't - There are sooo many topics about this in the forum and even articles on the internet… I don't want to explain everything, that was already explained by persons, who can do it much better than me.


Nevertheless, here are the basics: Blocks are merged to chunks (e.g. 16x256x16 blocks), so only the according chunks need to be updated when the block is added/removed/whatever. The tricky thing when rendering is to only render the visible faces - If you have a huge mountain of blocks, you only need to render the blocks on the surface. And even in this case, only the faces that point outwards. ;)
The framework does all this for you, no need to worry. You, as user, can just add/remove blocks as you wish without knowing about the chunks, the optimized geometries etc. etc.


⇒ You add a block ⇒ You see the block :)



== Performance

The performance is good I think - In a test case I had a scene with 1.350.000 blocks (in 4x1x4 chunks of the size 16x256x16) and 20 movements of a block per second - The result was 1200 FPS. The average time to generate the optimized geometry for a chunk was 5ms.


Of course, there are cases when every face has to be rendered - But even in generated worst cases I never fell under 300-400 FPS, so it _should_ be fine for this stage of development (More about possible improvements later).



== Usage

Enough boring words about theory - Here's how you use the framework. :) This happens in different parts:


.  <<jme3/contributions/cubes/settings#,Settings>>
..  <<jme3/contributions/cubes/register_your_blocks#,Register Your Blocks>>
..  <<jme3/contributions/cubes/build_your_block_world#,Build Your Block World>>

After executing these steps, you should come up with an application like the <<jme3/contributions/cubes/basic_example#,Basic Example>>.



== Screenshots

Those are just some random screenshots that I made while creating and testing the block engine - They show in a nice way, what you can expect from the framework.


image:http///destroflyer.mania-community.de/other/imagehost/cubes/test_physics.png[test_physics.png,with="800",height=""]


image:http///destroflyer.mania-community.de/other/imagehost/cubes/etherblocks_third_person.jpg[etherblocks_third_person.jpg,with="800",height=""]


image:http///destroflyer.mania-community.de/other/imagehost/cubes/wireframe_view.png[wireframe_view.png,with="800",height=""]


image:http///destroflyer.mania-community.de/other/imagehost/cubes/test_shapes.png[test_shapes.png,with="800",height=""]


image:http///destroflyer.mania-community.de/other/imagehost/cubes/scene_mountains.png[scene_mountains.png,with="800",height=""]



== Tools

The framework offers several tools to play around with your blockworld:


*  <<jme3/contributions/cubes/tools/heightmaps#,Heightmaps>>
*  <<jme3/contributions/cubes/tools/noise#,Noise>>
*  <<jme3/contributions/cubes/tools/picking#,Picking>>
*  <<jme3/contributions/cubes/tools/serialization#,Serialization>>


== Further improvements / "Work-In-Progress" things

The following list contains things, that are *not yet* (!) part of the framework, but are considered as useful. If you have any ideas what's missing or what could be a cool feature, please tell me and (hopefully) it will be on the to-do list. :)


*  *Wiki:* List the included test applications (Tutorial, Heightmap, Noise, Modifications, …)
*  *Wiki:* List the included test data (Assets, Blocks, …)
*  *Wiki:* Write the missing instructions for some tools (e.g. how to create custom block shapes)
*  *BlockTerrain:* Support for dynamic counts of chunks (Automatically add chunks if an out-of-bounds block is added)
*  *Lights:* Implement a performant way to calculate if a block is affected by a “light block and modify its texture accordingly


== Where is this available?

This framework is available as plugin in the jMonkeyEngine SDK (“Tools → “Plugins), so users are able to download and integrate the library easily.


Hopefully, this thing will help some of you guys, when it's released - Any ideas, hints and comments on this are appreciated. :)

