buildat/design.txt

Buildat
=======
A Minecraft clone with vast extendability.

License: Apache 2.0

Client
------
Built using Polycode C++.

Module code is transfered from the server and run in a safe Lua sandbox.

Extensions are non-sandboxed code installed separately on each client.

Server
------
Built using C++ with most functionality in RCC++.

C++ modules can interface with each other by using Cereal.

Module structure
----------------
module
|-- deps.txt      << Module and extension dependencies
|-- <module>.cpp  << Server-side code
|-- include
|   `-- api.h     << Structures for interfacing between modules
|-- client_lua
|   `-- init.lua  << Client-side code (by convention)
`-- client_data
    `-- media.png << Data files (by convention)

Module behavior
---------------
No script or data transfer to the client is initiated by the core. Conventions
followed by builtin modules:
- module/client_lua/{init,*}.lua - builtin/client_lua
- module/client_data/*           - builtin/client_data

Modules can be unloaded at runtime. Handling of client-side state is left up to
the C++ modules themselves.

The first module to be loaded is called __loader. It loads all other modules.

C++ modules can use the core/ and interface/ headers. Everything else is
considered unstable.

C++ modules are run in threads, and everything they can officially access is
thread-safe.

C++ modules can provide direct library functionality inlined in their include/
files. See builtin/network as an example.

Startup sequence and what the module should do:
- constructor     : Don't access other modules. Throw on fatal errors.
- init()          : Subscribe to events; access other external things.
- "core:start"    : Start doing whatever the module wants to actively do.
- "core:continue" : Continue doing stuff after a reload.

Dependencies: deps.txt
----------------------
File format: One entry per line. Indentation for presentational purposes only.

Module entry:
  <module_name> <options>
Extension entry:
  extension:<extension_name> <options>

Options:
? - Optional dependency
r - Reverse dependency; load before the specified module (not for extensions)

Example:
  network
  plants ?
  stuff ?r
  extension:ecs2

Network protocol
----------------
(Type, length, data) tuples on TCP. In the future TLS can be taken into use. A
name->type registry is used for determining numeric packet types.

Data is freeform. Types 0...99 are reserved for initialization.

Core uses cereal's portable binary serialization, except for low-level packet
streaming.