Kandria Mods

Kandria allows you to create mods to add new levels, change existing game behaviour, add new gameplay elements, customise the appearance, and more.

Managing Mods

The easiest way to manage your mods is to use the in-game mod manager, accessible from the main menu.

Installed Mods

This tab shows the locally installed mods and allows you to activate and deactivate them. When a mod is activated it loads in all of its content and potential modifications. Similarly, deactivating a mod should unload its content and undo modifications. In most circumstances you do not have to restart the game for the changes to take effect.

Worlds

Here you can browse all the worlds that the mods have provided. A mod may provide any number of worlds at once, and with this menu you can load into any one of them, or even directly jump to editing them.

NOTE: save data for mod worlds is always saved to your most recent save file.

Discover

With the discover tab you can discover new mods that the community has uploaded. The top search field allows you to query mods by name, and with the sort box change the order in which the mods are displayed. Note that you need an active internet connection in order to browse mods.

When you click on a mod you'll get a detail view with the description and preview, as well as a button to download and install the mod if it isn't available locally yet. Note that even after downloading a mod it won't be active right away, you have to go back to the Manage tab to activate it.

Import Mod

This button allows you to pick mods that you manually downloaded or got from elsewhere and pull them into the game. Kandria will copy the mods to the mods/ directory at the game root to do this. You can also drag a mod file into the game window to do the same.

Create Mod

With this button you can quickly create a new mod. If the mod type is set to world, it will also automatically create a new empty world for you and load you into its editor. If the mod type is other, it will instead open the mod source directory, so you can start editing the source files.

Creating Mods

A mod can provide any number of worlds. Any zip files and directories beginning with world within the mod directory will be registered as worlds when the mod is activated. No other setup is necessary.

NOTE: Creating mods that do more than provide new worlds is currently not officially supported. Many things will not be convenient or may break in the future. If you're not ready for some hacking, please wait for the official modding support release!

If you need to do more, currently only the module-v0 format is available, which gives you a setup.lisp file that you can edit. It is a plain Lisp source file that is loaded when the mod is activated.

Updating Mods

Once a mod has been created, you can update its title, the preview image, and the description from the mod manager. Just click on / activate the relevant part. Note that i you are not the owner of the mod, it may deny you from changing it.

Alternatively, you can also edit the mod files directly. Use the Open Source Directory button to visit the contents, and see Mod Structure for details on the contents. If you edit the files, the mod data won't automatically update in-game unless you deactivate and reactivate the mod first.

After updating the mod data, you might want to update it on the remote if you've uploaded it to Mod.io. Simply using the Update on mod.io button should synchronise the data for you.

Sharing Mods

Once you've created your mod you'll probably want to share it with friends or the community at large. Kandria offers two ways of doing this.

NOTE: We do not tolerate any mods that promote hate speech, hate speech symbols, or include discriminatory or bigoted content such as racism, homophobia, transphobia, or xenophobia. If your mod should make others uncomfortable, we will ban it and you from our platforms.

Direct Transfer

You can share mods with other people directly. This is best if you'd like your mod to stay private.

1. Navigate to your mod source directory. It should be located within kandria's root folder under mods/.

2. Create a ZIP file of all the mod files in its directory.

3. Share the ZIP file through whatever methods you choose.

3. Your friends can simply use the Import Mod option in the mod manager and select the mod zip file after downloading it.

Mod.io

Kandria has an official mod.io directory where anyone can share, download, and rate mods regardless of how they purchased Kandria.

1. Navigate to your mod entry in the mod manager.

2. Click the Upload to mod.io button. If you have not previously logged in, it will now guide you through a login process with mod.io.

3. Once login is successful, it will automatically upload your mod.

4. That's it! Your mod should now appear in the Discover tab under the mod manager.

Updating your mods works in the same way, if the manager notices that the mod exists on mod.io and that there's been a change to the local files, it will show an Update button instead. Simply pressing that will synchronise the data remotely.

Mod Structure

At its most basic, a mod is a directory that must contain a single file called meta.lisp. That file identifies the directory as a module with the following content:

(:identifier module :version module-v0)
(:id "6632CE56-9F1B-6EB3-712D-CC0ED9083E62"
 :title "Hello World!"
 :author "Shinmera"
 :version "1.0.0"
 :description "Shows a hello world textbox when loaded.")

Beyond the first line, the contents of both meta.lisp and the rest of the directory depend on the version used. Currently only module-v0 is supported.

module-v0

After the identifier line, the meta.lisp must contain a list of module metadata, with the following keys:

• id
  A UUID that uniquely identifies your mod. You should never create a UUID that clashes with that of an existing mod. When you create a new mod from the mod manager, a randomised UUID is created for you, which should be safe to use as collisions are insanely unlikely.

• title
  The title for your mod. This is completely arbitrary, but please keep the length short enough.

• author
  Some identifier for who made the mod. Again, this is arbitrary, and does not necessarily have to match the username of your account on mod.io.

• version
  A version identifier. You are encouraged to use the major.minor.patch format, but are not forced to do so.

• description
  A long, free-form description field. You can use the Markless document standard for extra formatting.

Aside from the meta.lisp file, the directory may contain any number of .zip files and directories that begin with world. All of those will be registered as worlds that the mod supplies, and will show up in the mod manager's world list if the mod is loaded. You don't need to write any code for this, the system will discover and register them on its own.

The directory may contain a preview.png which should be a 16:9 image that is used as the preview icon in the mod manager and the discovery browser.

Finally, the directory must contain a setup.lisp file. This file is simply loaded via the Common Lisp load function. The file must start with something like this:

(define-module 6632CE56-9F1B-6EB3-712D-CC0ED9083E62)

(in-package #:org.shirakumo.fraf.kandria.mod.6632CE56-9F1B-6EB3-712D-CC0ED9083E62)

Where the UUID you see must match the one from the meta.lisp file. Using the above code will ensure that you have all the necessary APIs available, and don't trample on the code of other mods or libraries. Past this point you can do pretty much anything, though please note that since the setup.lisp file is loaded every time the mod is loaded, this will be rather slow. You also cannot depend on any new libraries or other parts of the Common Lisp ecosystem that aren't already shipped with Kandria.

If you require more flexibility than is offered by this, please wait for the release of the official modding support update, which will include a far more capable system, as well as an actually stable API and documentation for it.

Additional Help

If you require more assistance, or are curious about other parts not covered by the documentation here, please don't be shy and stop on by our Discord. We have a channel dedicated for modding, and you can collaborate and ask questions there.