Here is a proposed system for managing mods that would want to add additional ids into the game, whether that be for new items, new blocks, etc. that borrows a bit of inspiration from Minecraft's Forge modding API.

Issues with integer IDs

The game currently uses integer ids to represent things. There are a few issues with using integer ids.

The first issue is conflicts between mods, where two mods both try and add something that corresponds to the same number. These issues are usually resolved through tedious config file management by users.

The second issue is conflicts between ids between host and user. This stems from the fact that configs can be used to change the value of ids, such as the host changing the ids for a mod and the user not having the changed config files. This is usually resolved by passing the config information around between users, whether that be done by the user or whoever distributes the mods.

The last issue is when new content is added to the game. If new content is ever added to the game, mods and the base game can end up trying to use the same integer id, causing compatibility issues. This is usually resolved by starting the floor of allowed ids sufficiently far away from the base game's ids.

Representing a new addition

Everything that would normally have an integer id in the game would also be required to have a string id. The SDK would support interactions only in terms of this string id. The formatting for these ids would be something like:

mod_prefix:item_name

Each mod would its on prefix, specified however it is appropriate, and would register its new additions with this prefix attached.

The base game would have its own reserved prefix, such as base or cubeworld, and the SDK would provide a standard mapping for this (e.g. a grass block is base:block_grass as defined by the SDK).

Registries

To store these new string ids, we will utilize some form of Registry. Each respective system that uses ids would hold its own registry. A registry, in simplest terms, is a mapping of string id to integer id. By default, this will contain the base game's mappings and will be populated during mod initialization.

In order to prevent changes in mods from changing the meaning of an integer id, persistence of each registry is needed. To implement persistence of registries, each registry would be saved alongside characters. This has a few implications alongside it, the major one being each character (and subsequently each client) can have different integer ids for the same string ids. This won't cause issues when playing alone, as the registries get saved/loaded with each character. However, in multiplayer, differences in integer ids can occur and need to be handled

The default registry

The default registry is how the loader will populate save files that don't already have a registry attached. To start, each default registry is populated with the base game data. Then, each registry will hold the next "free" integer id available, based on which id was last registered by the base game (potentially adding a large section of padded space in case Wollay ever returns to the living). During mod initialization phase, mods will be allowed to access registries and add their new string ids. When a new string id is registered, it takes the next available integer id for its mapping. After initialization, the default registry made read-only.

Initializing and modifying a Save's Registries

Registries attached to saves should only be modified when mods are added/removed. The cases for when this happen are below:

The very first time a save file is loaded/created, no registry will be present. The Loader will then copy the default registry to the save file and the save file will use that as its new registry.

If a save file already has a registry present, the loader will look to see if any new mods have been added to its default registry that aren't present in the save file's registry. If there isn't anything new, proceed normally. If there are new entries in the default registry, we will attempt to add them to the save file's registry. If an integer id conflict occurs, we let the save file registry allocate a new integer id for the string id that is being added.

In the event that the save file registry has an entry that isn't present in the default registry (e.g. a mod was removed), some sort of error prompt may be needed for the user to respond. Potential ways of handling this include removing anything that uses a removed mod's items and/or telling the user that a save was created/accessed with a mod and it is not actually loaded

Registries and Multiplayer Sessions

For handling multiplayer properly, we introduce a method of interpreting the host's registry. This method assumes that both users have the same set of mods that involve registering new things.

To start, when a user connects to a host, the host sends out to the connecting user all of its registry information. The user then stores this and uses it to interpret every related packet that the host sends out (e.g. item drops, block changes, etc). Likewise, the user will send its registry information to the host as well, and the host stores this and uses it to interpret anything the user might send to the host.

Whenever a relevant packet is sent/received, the recipient will look to the sender's register and interpret what string id the packet's respective integer id is referring to. It then uses this and looks up what integer id the recipient is using for that string id, replaces it, and then allows the packet to be processed.

Example 1: Interpreting a Packet

The host receives an item dropped packet from User A. Currently, the host has the following registries:

• Host Item Registry:
  • "items_mod:new_item" maps to id 56
• User A Item Registry
  • "items_mod:new_item" maps to id 59
• User B Item Registry
  • "items_mod:new_item" maps to id 60

The packet received from User A is a packet saying they dropped an item with id 59. The host gives this packet to the interpreter, where it looks to User A's item registry and discovers that they dropped a "new_item" from "items_mod". It then looks up what integer id the host is using for this item and substitutes that value into the packet. It then allows the host to continue processing this packet and handles the item drop. It then broadcasts that an item was dropped to other users, and User B receives the item drop packet from the Host that says the item dropped was an item with id 56. The process repeats, and User B successfully sees that a "new_item" is on the ground where User A drops it.

How differences in registries can occur

Suppose the Host and User A have the following sets of Mods:

• Host mods:
  • A B C
• User A mods:
  • A B C D

The following is true for the above mods:

• Mod A depends on Mod B
• Mod D optionally depends on mod C
• Mod B optionally depends on mod D
• Mod D is a client-sided mod only (it functions even with the host not having it present)
• Mod A, B, and C all register new items

The mod loading order would be the following, assuming mods are loaded by dependency and then by alphabetical order

• Host load order;
  • B A C
• User A load order:
  • C D B A

The end result of this is that both the Host and User A have the same set of required mods to connect to each other, but User A's default registry will have C's entries before B and A, whereas Host's default registry will have C's entries after B and A. Therefore, when User A creates a new save file and joins Host, they have an inconsistent set of registries and will need to use the interpreter to communicate.

End remarks

All these ideas are fairly abstract in nature and may ignore some finer implementation specific details. Additionally, it is open for discussion whether or not this is a viable way to tackle the issue.

Any and all input is appreciated.

Hi there,

I'm just new to modding and I'm trying to understand what's going on.
I'm using your Cube-World-Commands-Mod as an example, but for now I'm not even sure how to compile all that.

Could you maybe add a small Readme to explain how to setup a basic environment to start modding ?

Any help would be appreciated !

I was messing around with this a bit today and realized the return values of OnCheckInventoryFull don't work as they are documented.

Readme currently says:

• 1 - Override, CAN carry more.
• 2 - Override, CANNOT carry more.

But actually it is:

• 1 - Override, CANNOT carry more.
• 2 - Override, CAN carry more.

If that's not the case and I am just missing something, let me know.