The LevelZ File Format: Introduction

This will be a series of posts talking about the LevelZ File Format, a file format I created for my video games. The project is an open-source project under Calculus Games. It’s used in Combinatory and future games I plan to make.

So, what is it?

LevelZ is a file foramt designed to be a human-readable and human-designable way to create level data. It’s inspired by an older format I designed for one of my plugins, known as the StarCosmetics Structure format (*.scs). The format is designed to be easy to read and write, and is designed to be easily extensible.

Why not use JSON or YAML?

Both are great formats, but it’s not designed for human readability or design. It’s designed to be easily machine-readable, and is not designed to be easily extensible. I made LevelZ to be a format I could work on in the middle of AP Computer Science Principles when I was finished with my work.

In addition, JSON and YAML are not really structured for level data. They’re more for configuration or arbitrary data in general. LevelZ is designed to be a format specifically for level data, and is designed to be easily extensible.

What’s next?

The project has official bindings on the big few platforms: JVM, Kotlin Multiplatform, JavaScript, Python, and C/C++. As demand for the format grows, I’ll add more bindings, but the big few ones are already out there.

What does it look like?

Here’s a sample LevelZ file according to LevelZ-File/examples:

@type 2
@spawn default
@scroll none
---
grass: [0, 0]
grass: [0, 1]
dirt: [1, 1]
stone: (-3, 3, 0, 0)^[2, 2]
end

There’s a few things going on here.

• @type 2 is the type of the level. LevelZ supports 2D and 3D levels, and this is a 2D level.
• @spawn default is the spawn point of the level. This is where the player will spawn. The default value is [0, 0].
• @scroll none is the scrolling type of the level, if it is an auto-scrolling level. The acceptable values are none, horizontal-right, horizontal-left, vertical-up, and vertical-down.
• --- is the start of the level data. Everything after this is the level data.
• grass: [0, 0] is a tile at position [0, 0] with the texture grass. The same is true for the next line at [0, 1].
• dirt: [1, 1] is a tile at position [1, 1] with the texture dirt.
• stone: (-3, 3, 0, 0)^[2, 2] is a tile at position (-3, 3) with the texture stone. The ^ is a matrix operator that fills in a 7x1 rectangle (from X=-3 to X=3) with the texture stone, centered at [2, 2].

How do I use it?

The format is designed to be incorporated with existing game engines and visual technology. The bindings simply provide information from the level data that are then drawn on the screen using your own methodology.

I wanted to design it this way because I wanted to be able to visually understand what the level would look like and be able to manually edit it in a text editor. This is why I designed LevelZ to be human-readable and human-designable. If possible, I want to design a visual editor as both a desktop application and a website to help visualize with actual graphics.

Conclusion

This was a short introduction to the LevelZ File Format. There will be more posts explaining more details about the format and how to use it in your games. Stay tuned!