173 lines
5.2 KiB
Plaintext
173 lines
5.2 KiB
Plaintext
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).
|
|
|
|
|
|
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).
|
|
|