Buildat Client API ================== Lua code is run in two subtly different environments. Interface common to both environments ===================================== buildat.bytes(data) -> table 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/") 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: = require("buildat/extension/").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/"); this is the equivalent of using require("buildat/extension/").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: cereal.binary_output(value: , 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).