Potato Minecraft Server

It runs on a potato.

Crates

potato - Binary crate for the main server, handles starting the server from the CLI. potato-server - Main server implementation. potato-api - Defines the api for modules to interact with the server. potato-data - Internal crate holding types and constants generated from minecraft datagen reports. Intended for use by the core module. potato-mod-core - Module implementing the core minecraft mechanics for the server. Compiled into the main binary and can't be unloaded. potato-macro - Macro implementations for both internal and external use.

Module lifecycle

On server startup:

1. on_load is called for all modules
2. reload_resources is called for all modules
3. on_resources_loaded is called for all modules

On module reload:

1. on_load is called for the module being reloaded
2. reload_resources is called for the module being reloaded
3. on_resources_loaded is called for the module being reloaded

Concepts

Data reload: A reload off all registries. Data-backed registries are automatically repopulated from the available datapacks and code-backed registries are cleared ready for population by code.

Plugins

Plugins are loadable (and unloadable) modules used to extend server functionality. Plugin loading and unloading causes a data reload as it might have inserted entries into a code-backed registry, which will get removed once the plugin is unloaded.

Plugin lifecycle (luau)

Server startup:

1. Plugin is discoverd and its init.luau file is executed. This should return the plugin table.
2. After all plugins are discovered, the dependency graph is calculated (TODO).
3. Plugins are loaded in order. The on_load of a plugin is called. This is the time to create your registries.
4. A data reload is executed.

Single plugin reload:

1. The plugins on_unload is called. This is when you should cleanup your registries.
2. The plugins on_load is called.
3. A data reload is executed.

New plugin load:

1. The plugins on_load is called.
2. A data reload is executed.

Plugin unload:

1. The plugins on_unload is called.
2. A data reload is executed.

Data reload:

1. All registries are cleared.
2. pre_data_reload is called for all plugins. This is the time to populate code-backed registries which may be required during the data reload.
3. A data reload is executed, populating all data-backed registries.
4. on_data_reload is called for all plugins. This is the time to populate code-backed registries which depend on data-backed registries.

Registry system

Types of registries

All types of registry can only be read at runtime, and are append-only during a data reload. No way to remove anything except for a full reload. This ensures that data stays available during server runtime.

Data-backed (reloadable): Replacing entries happens through a data reload. Adding entries outside of a data reload is impossible. A data reload causes the world and all clients to fully reload. The world is reloaded from disk and clients are kicked back into configuration for a registry sync.

Code-backed (static): Adding entries happens through code. Doesn't require a data reload so it can happen while the world is loaded. Clearing it is still only possible during a data reload as data-backed registries might depend on it.

IdMapper: A special type of code-backed registry that maps numeric IDs to instances of objects.