User Tools

Site Tools



In Chunk Stories, everything is either built-in to the engine or a mod. The core content ( the one that ships with the game ) is a mod. The separation is made clear and enforced in the different codebases. Let's look at the layout of any mod :

What does a mod look like

The structure of a mod is as follows: it's a directory ( or a zip archive ) with a mod.txt file at the root. It may contain an icon ( 'modicon.png' ), jar files and any other type of file.

Files within a Mod are called Assets, Mods are managed by a ModManager. Multiple mods can be loaded on top of another thus resulting in a Asset with the same name and path being provided by two different mods, in that case the mod with the highest priority will be the one we use. It is also possible to list the different copies of an asset using special methods in the ModManager.

Jar files can contain anything, but any class found inside them will be scanned and made available to use as a Custom class in content definition files. Jar files can also be plugins. There is no hard limit on the number of jar files that can be bundled inside a mod.

Content definition

Unlike other, degenerate modding tools for cubic games, content is defined in plain old text files rather than in Java using code. This approach lowers the barrier of entry to modding, accelerates the rate iteration and tweaks that one can make, and generally are a cleaner, proper way to do things. For this purpose the game employs a very simple custom file format.

More detailed specifications, including a grammar file can be found on the wiki page mentioned above.

voxel pinewood {
	material: bluntwood

voxel drygrass {
	textures {
		sides: ~side
		bottom: dirt
		top: ~top

voxel pineleaves {
	class: io.xol.chunkstories.core.voxel.VoxelLeavesLod
	opaque: false
	selfOpaque: false
	shading: 1
	hardness: 0.5

You can find a complete list of file formats used to define content here

Conventions & Paradigms used

Master & Client

In the code and engine internals, you can see such nomenclature :WorldClient, WorldMaster, isMaster() etc …

  • Client means 'Is an end-user : it can render the world, control entities etc'
  • Master means 'Runs the world logic, manages end-users and has the authority on it'

I did not use 'client' and 'server' for good reasons : there is no reason a client can't also be a master : this exact situation happens when you have a local singleplayer or multiplayer world running on the just a client executable.

Sides and axises

These sides are used face-related operation such as block selection or culling.

  • 0 LEFT (X-)
  • 1 FRONT (Z+)
  • 2 RIGHT (X+)
  • 3 BACK (Z-)
  • 4 TOP (Y+)
  • 5 BOTTOM (Y-)

As you can see, the Y axis is height, X is east-west and Z north-south.

Voxel data storage format

The engine stores all voxels in 32-bit signed ( Java won't allow unsigned :c ) ints, packed in 32x32x32 cubical chunks, packed themselves in 8x8x8 regions.

These ints are composed as : 0xMMBSIIII

0→15 16-bit I blockID, allowing for 65536 different blocks types. You shouldn't work with those in raw form, use Voxels instead
16→19 4-bit S Sun light from the sun
20→23 4-bit B Block light, “yellowish” light from torches etc
24→31 8-bit M 8-bit metadata, extended from 4 bits in previous file formats revisions

Content IDs & Servers

For some technical aspects of the game, the name of a voxel, entity, etc can't be used to save it to the disk, because doing so would be immensely costly in terms of disk space and CPU overhead. Instead what the game does is assign everything that may be saved in large quantities an integer ID. This is done automatically by the game engine, and you should not really have to worry about it. But there are some subtleties you need to be aware of:

The game allocates IDs for every named definition, even if it is unused. If a mod declares 4'000 voxel types, then these will be reserved at the loading stage rather than when actually placed. This is for simplicity and robustness sake.

The game does not dis-allocates IDs automatically. If you load the game with said mod that uses up 4'000 ids slots, then remove that mod, the IDs will not be reclaimed automatically, and you will get a warning prompt if you try to load that world without the necessary mods loaded. If needs be, you can edit yourself the 'content-ids.txt' file in the world directory, but be warned this may mess up your save badly.

The servers send you their active mods and their IDs mapping at connection time. The process should be painless.

mod_generalities.txt · Last modified: 2018/09/10 12:28 by gobrosse