buildat/doc/client_api.txt

Buildat Client API
==================

Lua code is run in two subtly different environments.


Interface common to both environments
=====================================

buildat.bytes(data) -> table<int>

buildat.dump(value) -> string

buildat.Logger(module_name) -> object
	:error(message)
	:warning(message)
	:info(message)
	:verbose(message)
	:debug(message)

buildat.send_packet(name, data)

buildat.sub_packet(name, function)

buildat.unsub_packet(function)

buildat.run_script_file(name)
- Run script file gotten from server in sandbox environment


The extension environment
=========================

Extensions and the client boot-up code is run in the extension environment. It
is a raw Lua environment with no sandboxing or other rules.

Some of the sandbox-specific functions are not available or do not work normally
in the extension environment.

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. When sandboxed code
requires the module, it only gets the plain safe interface.

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

buildat.connect_server(address)
- Address may include port in format "host:port" or "[host]:port"

buildat.extension_path(name)

The sandbox environment
=======================

All code sent by the server to the client is run in the sandbox environment.

buildat.make_global(table)
- Copies contents table into the current global sandbox environemnt. It will
  still not leak into the scope of other files running in the sandbox. Useful if
  you want to remove the "namespace table" of an extension.

buildat.disconnect()
- If connected from menu, quit to menu (client state is reset by restarting it)
- If connected from command line, close the client


Safe interfaces of built-in extensions
======================================

Use extensions in this way:
  cereal = require("buildat/extension/cereal")
  cereal.binary_output(...)

You can use buildat.make_global like this:
  buildat.make_global(require("buildat/extension/urho3d"))
  local scene = Scene()

cereal
------
cereal.binary_input(data: string, type: object) -> value: <ny>

cereal.binary_output(value: <any>, type: object) -> data: string

Example usage (by using an object as the base structure for value):
	type = {"object",
		{"a", "byte"},
		{"b", "int32_t"},
		{"c", "double"},
		{"d", "string"},
		{"e", {"array", "string"}},
		{"f", {"object", {"x", "int32_t"}, {"y", "int32_t"}}}
	}
	input_value = {
		a = 128,
		b = 1000,
		c = 3.14,
		d = "Foo",
		e = {"Bar1", "Bar2"},
		f = {x=1, y=2},
	}
	data = cereal.binary_output(input_value, type)

	-- Data can be now sent over network or be saved on disk

	output_values = cereal.binary_input(data, type)

urho3d
------
Whitelist-based wrapper for the Urho3D Lua API.

NOTE: The whitelist is grossly incomplete. Please extend it and submit a pull
request. It is found in these files:
* extensions/urho3d/safe_globals.lua
* extensions/urho3d/safe_classes.lua
* extensions/urho3d/safe_events.lua

File paths and other things are converted automatically.

Additions to regular Urho3D:

SubscribeToEvent(event_name, callback)
- callback: function(event_type: string, event_data: VariantMap)
SubscribeToEvent(object, event_name, callback)
- callback: function(object, event_type: string, event_data: VariantMap)
- Callback can be a function, unlike in plain Urho3D where it must be a global
  function name.
- Return value: Name of the generated global callback which can be unusbscbribed
  from Urho3D via UnsubscribeFromEvent(event_name, callback_name).


Unsafe interfaces of built-in extensions
========================================

urho3d
------
The default unsafe interface is the same as the safe interface. It is so to
enforce interoperability between modules and extensions.

If you get an error like this:
  'Disallowed type: "userdata"; Allowed types: ...'
You probably are giving a non-sandboxed object to an interface that requires
sandboxed ones.

An actual unsafe Urho3D interface is available in:
  require("buildat/extension/urho3d").unsafe

DO NOT USE the unsafe version of urho3d unless specifically needed. All
interfacing with other extensions and module code has to be done using the
sandboxed version in order to make interfacing possible between all of them.

The unsafe version of the urho3d extension actually just wraps to the global
environment, except for the additions to the API documented here.

Note that due to technical reasons Urho3D's API is currently always globally
defined in the extension environment, but this will not be supported in the
future.

Additions to regular Urho3D:

SubscribeToEvent(event_name, callback)
- callback: function(event_type: string, event_data: VariantMap)
SubscribeToEvent(object, event_name, callback)
- callback: function(object, event_type: string, event_data: VariantMap)
- Callback can be a function, unlike in plain Urho3D where it must be a global
  function name.
- Return value: Name of the generated global callback which can be unusbscbribed
  from Urho3D via UnsubscribeFromEvent(event_name, callback_name).