buildat/design.txt

Buildat
=======
A minecraftlike 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 runtime-compiled C++ modules.

Module structure
----------------
module
|-- deps.txt      << Module and extension dependencies
|-- <module>.cpp  << Server-side code
|-- 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:unload"   : Module will be unloaded immediately after event handler.
- "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:<module_name> <options>
Extra CXXFLAGS:
  cxxflags:<flags>
Extra LDFLAGS:
  ldflags:<flags>

Options:
? - Optional dependency
r - Reverse dependency; load before the specified module

Example:
  module:network
  module:plants ?
  module:stuff ?r
  ldflags:-lsasl2

Extension structure
-------------------
extension
`-- init.lua  << Loaded when the module is required
`-- init.cpp  << Compiled as a Lua module and loaded if init.lua doesn't exist

Extension behavior
------------------
Extensions use the new Lua 5.1/5.2 module interface.

If an extension wish to provide an interface to sandboxed code, it should
implement table "safe", which contains the safe interface.

Extensions and modules use require "buildat/extension/<name>" to use extensions.

The __menu extension is specially loaded automatically at client startup if no
server address is provided on the command line. __menu can then connect to a
server. When disconnecting from a server, the whole client window is closed and
reopened.

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.