---

📖 Table of Contents

• How to contribute
  • Identify
  • Decompile
  • Fork
  • Examine
  • Commit
• How to use
  • Clone
  • Make a start-script
• Design decisions
  • Why ECS?
  • Why the lib?
  • Why zig?
• Goals
• License

---

How to contribute

NOTE All the following steps require you to have a version of git and zig 0.15.2 running on your system.

Identify

... a feature you'd like to add or an issue to work on. You should always create an issue or a draft-pr describing what you want, before considering adding a major feature.

Decompile

... the latest version of Minecraft using Parchment mappings. The main branch currently targets Minecraft 1.21.10.

Alternatively, you may use GitCraft for this task. If you choose to use GitCraft, run the command

./gradlew run --args="--mappings=mojmap_parchment --only-stable"

in the GitCraft directory and keep in mind that you may have to implement this change beforehand.

Fork

... the main branch of this repository, so you can prepare your changes on there. Clone it to your system by running the command

git clone https://github.com/{your-name}/kommodo

in your directory of choice. And don't forget to set this repository as it's upstream by running the following command

git remote add upstream https://github.com/tn-lorenz/kommodo.git

in said directory. To test if it has succeeded, type

git remote -v

which should yield the following.

origin   https://github.com/{your-name}/kommodo.git (fetch)
origin   https://github.com/{your-name}/kommodo.git (push)
upstream https://github.com/tn-lorenz/kommodo.git (fetch)
upstream https://github.com/tn-lorenz/kommodo.git (push)

Now set-up a new feature branch by running

git checkout -b feat-{feature-name}

from the main branch.

Examine

... the vanilla Minecraft implementation. Translate it to idiomatic, ECS-compatible zig 0.15.2 code, as cleanly and efficiently as possible (SIMD would be goated!). When in doubt, consider if your code adheres to the core-principles and goals of this project.

Commit

... your changes to your fork and use the following commands in its directory:

git add .
git commit -m "{your-message}"
git push origin {your-branch}

Then you may open a pull-request by comparing on the github website.

NOTE This project strictly enforces the use of the conventional commits standard in the commit messages.

---

How to use

Clone

... this repository as described in the contributing guide. Then run the following command in the downloaded directory:

zig build

This will compile the binary to ..\kommodo\zig-out\bin from where it can be copied to any directory you like.

Make a start script

in the same directory as the compiled binary and run it. The following are some examples for different operating systems.

Windows start.bat

@echo off
echo Starting kommodo...

kommodo.exe

pause

Linux start.sh

echo "Starting kommodo..."

./kommodo

read

---

Design decisions

This section briefly explains the thought-process behind the key-principles of this project's design.

Why ECS

A Entity-Component-System (ECS)-based architecture allows for data-oriented-design, cache optimisation, easy parallelization and massive concurrency. It should also be easy and ergonomic to work with, thanks to zig's comptime capabilities.

Why the lib

Kommodo aims for providing both a fully-working implementation of the current Minecraft vanilla server, complete with plugin support and a library that allows for bespoke implementations, similar to Minestom.

Why zig

As previously noted, zig provides great utility with it's compile-time capabilities. The new std.Io interface enables a high level of customization, for example switching to an event-based async runtime, as provided by libxev would be trivial. Being a low-level language, it's also more than suitable for thorough optimization.

---

Goals

Provide a native, easy to use, flexible and powerful ECS library
Provide a fully-implemented example of a vanilla server with plugin support as a downloadable binary
highly optimise for data-oriented-design, multi-threading, parallelisation, SIMD and customization
Utilise the full power of the Io interface and event-based runtimes

---

License

This project and all of its content is licensed under the Apache License 2.0.