pixelguys/cubyz

Voxel sandbox game with a large render distance, procedurally generated content and some cool graphical effects.

Cubyz

Cubyz is a 3D voxel sandbox game (inspired by Minecraft).

Cubyz has a bunch of interesting/unique features such as:

• Level of Detail (→ This enables far view distances.)
• 3D Chunks (→ There is no height or depth limit.)
• Procedural Crafting (→ You can craft anything you want, and the game will figure out what kind of tool you tried to make.)

About

Cubyz is written in Zig, a rather small language with some cool features and a focus on readability.

Windows and Linux are supported. Mac is not supported, as it does not have OpenGL 4.3.

Check out the Discord server for more information and announcements.

There are also some devlogs on YouTube.

History

Until recently (the Zig rewrite was started in August 2022) Cubyz was written in Java. You can still see the code in the Cubyz-Java repository and play it using the Java Launcher. // TODO: Move this over to a separate repository

Originally Cubyz was created on August 22, 2018 by zenith391 and ZaUserA. Back then, it was called "Cubz".

However, both of them lost interest at some point, and now Cubyz is maintained by IntegratedQuantum.

Run Cubyz

The Easy Way (no tools needed)

1. Download the latest source code
2. Extract the zip file
3. Go into the extraced folder and double click the run_linux.sh or run_windows.bat depending on your operating system.
4. Congratulations: You just compiled your first program!

It doesn't work?

• If it doesn't work and keeps running for more than 10 minutes without doing anything it can help to kill and restart the process. A few people seem to experience this, and I have not found the cause. It might also help to delete the zig-cache folder.
• If you see an error message in the terminal, please report it in the Issues tab or on the Discord server.
• Otherwise you can always ask for help on the Discord server. If you are unable to get it compiling on your machine, you can also ask on the Discord server and we may compile a release for you.

Note for Linux Users:

I also had to install a few -dev packages for the compilation to work:

sudo apt install libgl-dev libasound2-dev libx11-dev libxcursor-dev libxrandr-dev libxinerama-dev libxext-dev libxi-dev

The Better Way

1. Install Git
2. Clone this repository git clone https://github.com/pixelguys/Cubyz
3. Run run_linux.sh or run_windows.bat, if you already have Zig installed on your computer (it must be a compatible version) you can also just use zig build run
4. When you want to update your local version you can use git pull. This keeps everything in one place, avoiding repeatedly downloading the compiler on every update.

Contributing

Code

Try to follow the style of the existing code. The check_format.py file can be used to find violations of indentation and line endings. // TODO: Add a full style guide
If you have any more questions, you can ask them over on Discord.

Textures

If you want to add new textures, make sure they fit the style of the game. If any of the following points are ignored, your texture will be rejected:

1. The size of block and item textures must be 16×16 Pixels.
2. There must be at most 16 different colors in the entire texture.
3. Textures should be shaded with hue shifting, rather than with darkening only.
   If you are not sure how to use hue shifting, here is a video that explains it well.

cubyz's Issues

Lighting

The game should have some flood-fill based ambient lighting.

Difficulties

Minecraft's lighting algorithm is fairly simple, however it is also fairly limited due to only having 16 different light values and 2 light channels. This means that the light is not colored and a torch can at most light 16 blocks in one direction.

In Cubyz I would like to have colored lighting (e.g. colored light sources and colored light absorption through glass).

Additionally I would like to have long range interactions. Especially for larger caves minecraft's lighting model looks wrong because torch light cannot reach the opposite wall.

Now bother of these come at a heavy performance cost. 3 more color channels would increase the cost by 3×
Increasing the light range by 2× would increase the cost by 2³ = 8×

Solution Idea 1

Rather than doing lighting on a per-block level, it should be done at a larger scale.

This can be done with a coarse graph structure of the transparent volumes, and traversing that graph on light updates.

Problems with that approach

• how should the terrain be coarsened?
• which nodes should a given block sample to achieve proper smooth lighting?
• What happens at boundaries between different media, like colored glass and air? We wouldn't want white light to bleed through a colored glass pane.

Solution Idea 2

Store column-wise runlength-encoding data.
For each run we only need to store one light value, remaining values are inferred from the block properties and the distance to that light source.
When there is multiple lights that hit the run in different places, then the run should be split into 2 smaller runs.

Problems

• The number of runs will change often during the propagation. This means that a lot of memory should be preallocated, leading to wasted memory. One idea would be to store each run in a different array of 32² elements. As soon as one column exceeds the number of arrays, a new array would be allocated. This wastes a bit of memory, but should use less cache-memory than fragmented allocations.

Random tick events for growable crops/saplings and meltable blocks

Each chunk should keep a list of tickable blocks.
Each tick for every a random value is compared against the probability of that block. When that's true, a callback function will be executed for that block, given the chunk and the position inside of it.

This requires #76

Workbench

Collision Detection

The player should and other entities slide along walls. And not fall through the ground.

Finish Block Rotation

See the TODOs in rotation.zig. Some functionality from the java version is still missing.

Biome Generation Rewrite: Remaining Work

• Balance the existing biomes and their sizes
• Fix the precomputed value noise number distribution
• Try different resolutions of the biome grid. Maybe 16×16 gives better results?
• Remove the debug image
• Go through the code and look for remaining TODOs
• #107
• #183
• #188

Friction and Air resistance

The player should slide over ice and move slower through thicker air/fluids.

Fluid/Gas System

Fluids and gases should be stored and simulated outside the normal voxel volume.

Goals

• heavy liquid should flow downwards
• light gases should flow upwards
• biomes should have an associated liquid/fog block. Whenever a block in that biome is broken, the gap must get filled with the right fog/fluid block
• Fluids/Gases should exist in seperate memory to allow for underwater fences and similar
• Fluids should not propagate endlessly, flooding the entire world

Relaxations

• fluid volume does not need to be preserved
• the flow does not need to be realistic
• big bodies of water like the ocean can be assumed as infinite, as long as they don't flood the entire underground

Evaluate voxel model performance considering Flowers and Grass

I would like to use voxel models for flowers and grass.
The current rendering system uses parallax raymarching for voxel models. This may not work very well for grass and flowers which are mostly air and have lots of detail.

Flowers/Grass would add a full layer of raymarched geometry on the ground.
Additionally the grass/flower models would have lots of details.
So overall parallax raymarching might be too expensive for this.

If this fails other approaches, like billboard textures, need to be considered.

Allow blocks that store items.

This would require storing a list of all inventories for each chunk.

Downloaded but frezee

So at first It said that a new server version was avaible and then all ok I cliked play and it didn't pass from there

Something is wrong

The game is using almost 100% of my GPU with only the game open.
Its a RTX 2060

55% to 70% on the main menu.

Buoyancy

The player should somewhat float in water and heavier fluids.

Entities Rendering

Entities are technically present in the game except they are not rendering, this issue will be for anything about making entity rendering.

• Load Models
• Display Models
• Dynamic Models (e.g. ground item)
• Animation

Snow should be not solid.

Version java check

installed 18 java, but said "it`s old need 11 at least not 8"

Resources Needed

This is a list of all assets(textures, models, sound/music) Cubyz already has or still needs.
Make sure to check the style restrictions of our textures before contributing.
If existing, the current version is shown.
Many textures on this list are only placeholders and need to be remade.

If you want to create one of them, comment on this issue or do so on our discord server.
The general format of the textures is 16×16 (apart from special models). No other resolution will be accepted.

Notice: This list only contains things that are already in the game. If you want to create a new item/block/entity, feel free to suggest it here on github or on our discord server. New suggestions are always welcome!

Textures

Blocks

(Temporal) Image	Name
	Cactus
	Coal Ore
	Cobblestone
	Diamond Ore
	Glass(and Colored Glass)
	Grass (on soil)
	Grass (vegetation)
	Gravel
	Ice
	Iron Ore
	Lava
	Mossy Cobblestone
	Oak Leaves
	Oak Leaves (transparent)
	Oak Log
	Oak Planks
	Oak Top
	Sand
	Snow
	Snow (on soil)
	Soil
	Stone
	Torch
	Undefined
	Water
	Workbench

Items

(Temporal) Image	Name
	Apple
	Coal
	Diamond
	Raw Meat
	Stick

Entities

(Temporal) Image	Name
	Pig

Other

(Temporal) Image	Name
	Crosshair
	Breaking animation (0)
	Breaking animation (1)

Inventory

(Temporal) Image	Name
	Inventory Slot
	Inventory Slot (selection overlay)

Status Bars

Beginning Empty	Middle Empty	End Emtpy	Beginning Full	Middle Full	End Full	Crack	Icon	Name
								Health Bar
								Hunger Bar

3D-Models

Block Models

• Cube with all faces the same texture
• Cube with all sides the same texture
• Cube with all faces different
• Torch
• Fence
• Pillars
• Doors
• Lever
• Button
• Chest
• Grass model
• Player Model
• Quadruped models
• Stellar Body model (as a torus)

Sounds and Music

Music

• Game music

Sounds

• Sound effects for everything

Inventory Enhancement: The Bag

Just like a normal bag, you can throw things in at the top, but if you want to search something in there, you have to start taking things out of it.

In the game the bag would be represented by a single item slot, where you can access the top-most item in the bag, or put new stuff into it.

Overall this allows expanding the inventory, while also encouraging some strategy when it comes to inventory management.
Which items do you want to access quickly? Which items can you just put into the bag?

Internally this can be represented by a Stack data structure.

In the future, there could also be capacity upgrades to the bag.

Cubemapped LOD

The idea would be to draw all chunks past a certain distance to a cubemap over the time of a few seconds.
Then the cubemap gets drawn behind the rest of the terrain.
This should reduce the number of triangles drawn, as well as the complexity of the fragment shader for distant terrain, at the cost of temporal inconsistency.

Not all LOD should be cubemapped however. Otherwise the effect probably gets too visible on faster movement.

World Creation Screen

In the World Selection Screen there should be a button that leads to the world creation screen.

There the player should be given the opportunity to choose a name.

When creating the world a few files need to be created. And then the world can be opened just like in the code for the world selection screen.

Swimming

The player should have some freedom of movement depending on the resistance of a fluid/gas.

Smaller-sized blocks

To allow more details and artistic construction, we could make the block size smaller (to 1/2 meters or 2/3 meters). However this would require the following changes:

• Multiblock structures
• Ability to place multiple blocks at a time
• Ability to remove multiple blocks at a time

Skybox

The game should have a skybox consisting of dynamic stars, the sun and maybe some clouds.

Prevent repetitiveness of textures

Textures are fairly repetitive when seen on a flat surface, so it would be good to have some sort of randomness to them.

(Some) Approaches

Random texture rotation

This can be seen in minecraft, but it is limited to a small number of blocks, like stone(→ flat texture) or grass/sand(→ random texture).
Because of that it may be a good start, but doesn't work in all cases.

Random texture variants

This can be seen on the cobblestone texture in the java version. While this definitely helps, the texture still looks somwhat repetitive, due to the fact that the borders of all texture variants need to match.

Random white noise overlay

The idea would be to only apply a layer of white noise to the texture. This would be fairly cheap, but it would only work well for noisy textures like grass/dirt/sand.

Fully procedural Textures (3D)

This approach can be seen in the procedural_attempt branch or in seperate repo I made to experiment.
In these I used a few layers of simple noise, and as you can see that worked quite well for some blocks:

However it ultimately failed due to poor performance (an extra 4ms per frame) and because it was too limited for the crystal block and cobblestone textures which require more detail.

Large 2D textures

Larger textures, such that still only 16×16 are drawn per block, would make it repeat at a larger scale.
However these textures would not match at the sides. (which hasn't bothered anyone in minecraft, so it could be a non-problem)
Additionally no artist would want to make giant textures by hand, so a procedural system is needed.

High coordinates collision bug

Collision doesn't seems to work at high coordinates (~1.8-e7 x/z)

Procedural Crafting (Remaining Work)

• Swords
• Throwing Weapons
• Balancing
• Material Effects
• How to handle other tools?
• Discoverability? How does the player know what tools they should make?

Entity AI

Not sure how that would work out precisely.
But in general the should allow going towards some targets and there should be specific functions for attack patterns.
Additionally the AI should be generic such that one could switch the AI to a different body.

Block Breaking

Block placing is already implemented, so this should be relatively easy.

Make it illegal to place blocks inside of the hitbox of entities

Requires #88

Protector Block

The protector block protects a chunk from modifications by another player.
Protector blocks can be shared between players, to allow team play.
Additionally a weaker version(that allows placing some blocks like torches) of the protector block can be owned by bosses. This allows protecting a dungeon until the player defeats the final boss.

Keep some chunks around the player loaded on the server.

This is important for entities and block ticks.

Sound System

There should be a proper sound system with the following features:

• stereo sound → this makes it possible to pinpoint the source in 3d space
• doppler effect → this makes it possible to determine the relative velocity (whether an enemy is moving towards the player)
• multiple tracks should be played at the same time, to allow for different sound sources + music integration.

Settings

• Crosshair + is visible when openning settings and in my example is over Fog
• At night some settings are not visible because of low light and colour selection
• I have a very good pc hardware but when I increase Render Distance and LOD Factor the game crushes and doesn't respond
• Mouse sensitivity is an important setting as well
  

Near Plane Clipping Problems

The near plane is currently at 0.1. It needs to be that high to avoid z-fighting in the distance

This is problematic at the surface of water or foggy blocks:

Possible Solutions

• Reverse-z-buffer: storing 1/z in a f32 depth buffer results in a better resolution across all values. However this caused a slowdown on my machine due to using GL_GREATER instead of GL_LESS (needs further investigation, maybe it's a driver or hardware issue). One possible solution would be to use the NV_depth_buffer_float extension which seems to be available on nvidia and amd (naturally it isn't available on my driver)
• drawing close geometry in a seperate pass, using glDepthRange (this makes getting the true depth from the framebuffer more complicated)

Different/Faster ground based modes of transportation

Walking is fun, but the world of Cubyz is gigantic. So at some the player will need a faster way to traverse the world.
Flying is also fun, but I want to give the players a reason to build things on the ground, and what better way to do that than building a rail or road network?

However building roads or rails can be quite tedious, when you need to build for thousands of blocks.
So maybe I need to add some automation tools?

Additionally there is the question what destinations the player needs to visit more than once? So between what places does the player need to travel?

Dynamic Structure Generator

A given civilization (usually) only use the building blocks that are available in the region.

A structure in the desert should be built from sandstone. A structure in the forest should be built from wood. A structure in the caves should be built from stone.

So I want to have a structure generator that takes a few common materials as input parameters as well as some secondary parameters like style or technology level.
Then the generator should make buildings out of the given blocks. These don't necessarily need to be unique, but some amount of variations would be desired.

Torches

Additionally to a rotation, there can also be multiple torches inside the same block, like in the java version.

Requires #68

BUILD FAILURE

The parameters 'executable' for goal org.codehaus.mojo:exec-maven-plugin:1.2.1:exec are missing or invalid

Entity Support

Entities should be roughly split into a body, an inventory and an AI.
The AI determines the goals of the entity.
The body determines how targets can be reached (swimming, walking or flying) and some general stats of the entity.
The inventory determines what tools and attacks the entity has.

All combinations of these should be allowed and additionally the player should be allowed to take control of different bodies.

Sub-tasks:

• Collision Detection #82
• Friction #83
• Buoyancy #84
• Swimming #85
• Entity AI #86
• Animation #87
• Entity Struct or ECS?
• Per-chunk entity storage
• Entity saving/loading
• Models

loot icons

In some cases when you are looting from low to high the loot stays mid air. They only fall when you destroy all nearby blocks, I assume it has something to do with the hitbox and the method used to fall.
Another thing I noticed is that sometimes when I destroy a cube of any material and falls, when it lands on a stone cube, the icon of the loot falls in to the stone making the icon visually not seen but still able to collect it if you go near it.

Entity Animation

There are a few possibilities, ranging from a simple system like in minecraft to inverse kinematics.
I would prefer the latter.

Gameplay trouble

Sometimes during the game or even at the start I stuck like on the screenshot and have no ability to return on ground surface

[Bug] Crafting items disappear when closing workbench

3 proposed solutions would be:

1. Block-storage system: Storing the items inside the block. This would also allow for other players to interact with said items.
2. Dropping the items to the ground, or on top of the workbench.
3. Returning the items back to the player.

Stairs, Slabs, Vertical Slabs, Vertical Stairs, ...

Some blocks should be divisible into 8 sub-blocks. ()
The player can use a chisel(or other tool?) to remove one of the sub-blocks.
When the last sub-block is removed the block drop is created.

Requires #68

Can we build Cubyz on android?

Hi there
Could you please support Cubyz to run on an android device?
Thank you so much!

Sky Islands

Inspired by the Aether there should be some islands in the sky a few thousand blocks above the player.

There will be some unique structures and bosses.

Reaching the sky biomes should be easy while flying (requires #71)

Additionally there should be some mountains that connect to the sky.
A player will eventually try to climb "that giant mountain in the distance" leading to the discovery of a new world.

The sky islands should not be visible from the ground, until the player gets close enough.

At the current state this requires some changes to the engine to allow generating terrain up there.

World Saving/Loading

This code needs to be ported from the java version.

Extremely sensitive mouse input

I came across this repo looking for a minecraft clone that i could mess with that wasn’t too big like terasology.

Anyways I made a new eclipse workspace and imported all three of the projects into it. No errors.

I then proceeded to build and run the client, only to find that the slightest movement of my mouse would cause the camera to violently spin around, making it impossible to do anything.

Any possible fix for this issue?

P.S. my OS is Windows 10 home.

falling from high altitude, hp to 0 but game continues with no death

Falling from high altitude makes hp go to 0, gets the screen red but the player doesn't die, there is no death or respawn.

Flying

There should be a special item (wings?) or equipment that allows the player to fly.

Apart from faster travel this also allows the player to reach the sky and there could be air battles with some enemies or bosses.

I think the progression should be similar to terraria, where each pair of wings has a different flight duration and speed.