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 get access to the interface of an extension.

If an extension wants to purely use the safe interface of an extension, it is
recommended to do this:
  <name> = require("buildat/extension/<name>").safe

API specific to the extension environment:

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.

Extensions are accessed by using require("buildat/extension/<name>"); this is
the equivalent of using require("buildat/extension/<name>").safe in the
extension environment.

API specific to 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.

Note:
	There is a gotcha in scene replication: Resources are replicated by resource
	name, meaning that resources like Materials and Models created or edited on
	the server will not be replicated on the client.

	If you wish to create or edit resources used by the replicated scene, you
	can use urho3d.sub_sync_node_added() to listen to node additions and name or
	otherwise augment your nodes in such a way that you can generate or set
	resources to each node that requires it.

	The sandbox wrapper adds the client-side components to the node using
	urho3d.LOCAL by default, avoiding the problems of accidentally using
	urho3d.REPLICATED on the client.

	Make sure to not set anything to that resource of the node on the server
	side, because then you will get unpredictable fighting between the one set
	on server-side and client-side.

	Example: games/entitytest/main/client_lua/init.lua

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.
- CreateNode and CreateComponent uses urho3d.LOCAL by default unlike native
  Urho3D. With urho3d.REPLICATED (native default) they will end up in the
  synchronized ID space and will be overridden by data coming from the server.

ui_utils
--------
UI utiltiies.

show_message_dialog(message)


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).


Miscellaneous
=============

You can create a client-side voxel registry like this:

local voxel_reg = buildat.createVoxelRegistry()
local atlas_reg = buildat.createAtlasRegistry()
do
	local vdef = buildat.VoxelDefinition()
	vdef.name.block_name = "rock"
	vdef.name.segment_x = 0
	vdef.name.segment_y = 0
	vdef.name.segment_z = 0
	vdef.name.rotation_primary = 0
	vdef.name.rotation_secondary = 0
	vdef.handler_module = ""
	local textures = {}
	for i = 1, 6 do
		local seg = buildat.AtlasSegmentDefinition()
		seg.resource_name = "main/rock.png"
		seg.total_segments = magic.IntVector2(1, 1)
		seg.select_segment = magic.IntVector2(0, 0)
		table.insert(textures, seg)
	end
	vdef.textures = textures
	vdef.edge_material_id = buildat.VoxelDefinition.EDGEMATERIALID_GROUND
	vdef.physically_solid = true
	voxel_reg:add_voxel(vdef)
	voxel_reg:add_voxel(vdef)
	voxel_reg:add_voxel(vdef)
	voxel_reg:add_voxel(vdef)
end