User Guide

Minecart is a program to version and organize game assets that can be shared through multiple game projects. Individuals and organizations who wish to use this software will have to set up a central directory on a machine that will serve as central or "remote depot" in Minecart terminology, this folder will contain all raw DCC e.g. png, gltf, wav, etc… files that need to be maintained and versioned. Note that this folder does not require a specific organization and this detail is left to users preference. Populating and or versioning existing DCC files can be achieved in different ways depending on the scenario:

• Starting fresh with an empty depot and create assets one by one. This is a viable option if we don't have many files as it is a manual and tedious process. This gives us the opportunity to review each file while populating our asset server.
• Starting from a big collection of DCC files. This is a scenario where manually uploading and reviewing each file is not feasible. Minecart comes with a little program called minecart-server-bootstrap.

Minecart Server Bootstrap

Along with the client application, we provide a very simple program that will discover all supported DCC files starting from a given directory recursively, and it generates a manifest next to it. The program will do this unattended. This command can be found under "Tools→Bootstrap". Of course, it is possible to run this process even for a single file, but it will not perform any upload to the server unless we are already connected to a remote, and we run it on the Remote Depot, in this case the SSHFS daemon will take care of replicating generated manifest files to the remote location.

Asset Depot

This program was created with the idea of storing raw assets on a remote machine. In the "Settings" window (accessible through the toolbar or through "Files→Settings") we can specify three fields.

• Local Depot - a place on a drive (most likely a local partition) where the program mounts a remote folder through SSHFS.
• Local Project Path - it can be any place but most likely the asset folder of a shard project. This is where the program downloads assets.
• Custom Remote Path - location on a remote partition. This field is used by the SSHFS daemon as the source directory when mounting into Local Depot Path destination. This can be used in different scenarios:
  • Assets are managed per-project. This will point to a remote location where DCC files are maintained.
  • Assets are managed across multiple projects. This will be setup once per studio and never changed.

This being said, Minecart can be also be used locally without requiring to set up an ssh server.

Remote Depot

Setting up a remote depot is quite easy, all you have to do is install an ssh server on you remote computer. To be able to mount a remote file system with Minecart though, users will need to generate an ssh key pair on their local machine and upload their public key to the remote server as sshfs does not allow password logins. You can find tutorials and how-to guides on the internet as Minecart does not require any particular setting.

Local Depot

As we wrote above, the application does not require a remote file system connection to operate. It is enough to set Local Depot Path to a shared or regular folder on the computer.

User Actions

Users can interact with assets on both views by right-clicking on assets displayed. The Project side is intended as a "read-only" view and users can only inspect asset files:

• Inspect: Open a read only window showing manifest properties and asset preview.
• Delete: Permanently remove a versioned asset from the project directory.

On the Remote Depot view users can perform multiple actions:

• Inspect: Open a window showing manifest properties and asset preview. In future releases this will also become an action to add tags and comments to the asset.
• Create New: Prompts the user to select a supported DCC file from a dialog, once chosen this file will be copied to the depot and versioned generating a manifest. In future releases this will also cook the asset to the binary engine resource format.
• Download: Get a copy of the manifest. In the future this will download the latest cooked binary engine resource.
• Delete: Permanently removes an asset i.e. manifest, DCC file and cooked resources from the minecart depot.

Clone

Clone the repository using git

git clone https://skyforge.crystalbluegames.com/CrystalBlueDevelopers/minecart.git

Build

Building the project is very simple. You can explore configure and build setting provided by CMakePresets.json in the root folder of the project. For example building Release configuration on Linux on amd64:

cd minecart
cmake --build --preset Debug-x64-Linux
// Build output
cd temp/build/Debug-x64-Linux/bin/

This will compile both minecart-server-bootstrap and minecart-client.

Manifest

The software communicates with a remote file system through SSHFS to maintain JSON manifests of raw game assets. As of version 1, a manifest looks like this:

{
	"manifestVersion": "1",
    "assetVersion": "0",
    "fileType": 0,
    "filepath": "/home/ndotl/Pictures/avatar.png",
    "guid": "18446744073188494350",
	"tags": [
		"model",
		"default_scene"	
	],
	"comments": [
		{
			"user": "llaspina",
			"date": "26.01.2026",
			"text": "This asset is cool!"
		}
	]
}

where:

• "manifestVersion" - each manifest version is relative to a set of fields that must be present in the manifest file.
• "assetVersion" - number of changes applied to the raw asset files.
• "fileType" - type of raw asset e.g. image, model, etc…
• "guid" - unique id of the asset that will be used to identify the game ready file or the editor asset. It is computed applying murmur hashing fvn1 to the "filepath". Stored as a string to avoid platform restrictions on integer size.
• "filepath" - location of the raw asset on the server.
• "tags" - user populated array of strings that can be used by Minecart or Shard Editor to filter assets.
• "comments - user populated comments on assets.

This manifest could potentially contain information on the resource in a shape that depends on the type of the asset. For example, images may add the following block to the manifest:

{
	...
	"image": {
		"type": 1,
		"format": 34,
		"width": 256,
		"height": 256,
		"depth": 1
		...
	}
	...
}

These extensions a currently not implemented in the system and it is not clear yet whether this information may be carried over from the manifest to a header block in the compiled resource file in order to easily load the resource during the game runtime. If these get implemented they will since version 2 of the manifest model and this guide will give a detailed explanation of each asset type extension block.

Roadmap

There are still loads of features we are looking forward to implement:

• Assets Tags editor. When inspecting an asset it should be possible to edit tags.
• Assets Comments editor. When inspecting an asset it should be possible to edit comments.
• Assets locking for editing. Avoid multiple users editing a file at the same time.
• Assets groups. We think it is logical to reference assets into packages or groups.
• Preview for all types of assets. We currently support it for image files. but it is just a preview of the full feature.
• Runtime format bake.