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.

sandbox.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 sandbox.make_global like this:
  sandbox.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).

replicate
---------
Interface to server->client synchronized (replicated) scenes.

replicate.main_scene
- Main replicated scene instance. To show it on screen, add a camera and a
  viewport. Add your local stuff to this as needed.
- You don't have to use this if you wish to synchronize your scene in a custom
  way.
- Remember to specify magic.LOCAL to both CreateNode and CreateComponent,
  otherwise they will end up in the synchronized ID space and will be overridden
  by data coming from the server.

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

urho3d
------
The unsafe interface consists of the namespace tables "safe" and "unsafe". Use
the safe interface unless the unsafe one is specifically needed:
  require("buildat/extension/urho3d").safe

This enforces 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 non-sandboxed 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).