Scripting/SNetwork

The SNetwork class is for communication needed between different clients/players. For communication between scripts and objects within a client please use Scripting/SShared.

IMPORTANT NOTE: Network functionality currently does not completely work in the Unity Editor, you'll have to upload your script to the preview/live server to see the effect. (You can tick the "Allow runtime script editing" option in the Scripting Runtime Component and it will let you edit this script live in the viewer.)

Members

SubscribeToNetwork

void SubscribeToNetwork (string key, Action<SNetworkMessage> callback);

Subscribes to network messages on 'key', will fire a Scripting/SNetworkMessage whenever a matching message is received

local scriptedObject = Space.Host.ExecutingObject;

local textValue = Space.Host.GetReference("Text");
scriptedObject.SubscribeToEvents();

-- This function gets used by other objects that are subscribed to the network
gotAMessage = function(arguments)
  textValue.UIText.Text = "Got a message with the argument " .. arguments.Message["someArgument"];
end

-- This function gets used by "this" object. Plus, it sends out a message to objects on the network.
local updateTextUI = function()
  textValue.UIText.Text = "Got a message with the argument Hi there!";
  Space.Network.SendNetworkMessage("helloworld", {someArgument = "Hi there!"});
end

-- Subscribe to network. Note that "this" object doesn't execute gotAMessage.
-- Only the other objects on the network do.
Space.Network.SubscribeToNetwork("helloworld", gotAMessage);

scriptedObject.OnMouseDown(updateTextUI);

-- "Text" used with GetReference is a UItext canvas object used to display the test text inworld. After you add UI > Text to your scene, drag the text object to the Object References section in your script.

SendNetworkMessage

void SendNetworkMessage (string key, IDictionary<object,object>);

Sends a networked message to every client with a subscriber listening on 'key'. The message itself can be a dictionary/table containing two columns and any network serializable type (string, float, int, byte, bool and arrays of those types)

This is a modified version of the example for *.Renderer.Material.SetTexture that demonstrates networking.

note that this example applies also to SubscribeToNetwork.

image = "mrlee.jpg"

server = "https://middleware.systems/"
obj = Space.Host.GetReference("Gino")

Space.Network.SubscribeToNetwork("smack", onSmack)

function hithere()

  resrc = Space.WebServices.GetImage(server .. image)
  obj.Renderer.Material.SetTexture("_MainTex", resrc)
  Space.Network.SendNetworkMessage("smack",{'smack'})

end

function update()

  resrc = Space.WebServices.GetImage(server .. image)
  obj.Renderer.Material.SetTexture("_MainTex", resrc)

end

function onSmack()

  update()

end

SetShardProperty

void SetShardProperty (string key, string value);

Sets a property named 'key' of the Shard to 'value'. Will persist until the Shard is shut down or restarted. (Use SPersistence for longer term storage)

local scriptedObject = Space.Host.ExecutingObject;

scriptedObject.SubscribeToEvents();

local testMsg = "Hello";
local updateTextUI = function()
  Space.Network.SetShardProperty("testKey", testMsg);
end

scriptedObject.OnMouseDown(updateTextUI);

-- Once this object is clicked, it will create a shard property with the key "testKey" and give it the value of "Hello".

GetShardProperty

string GetShardProperty (string key);

Gets a previously set key.

local scriptedObject = Space.Host.ExecutingObject;

scriptedObject.SubscribeToEvents();

local textValue = Space.Host.GetReference("Text");
local retrieved;

local updateTextUI = function()
  retrieved = Space.Network.GetShardProperty("testKey");
end

-- this method is called every frame, once "retrieved" gets a value, it displays in text
local onUpdateMethod = function()
  updateTextUI();
  if retrieved ~= nil then
    textValue.UIText.Text = "Retrieved msg: " .. retrieved ;
  end
end

scriptedObject.OnUpdate(onUpdateMethod);

-- "Text" used with GetReference is a UItext canvas object used to display the test text inworld. After you add UI > Text to your scene, drag the text object to the Object References section in your script.

SetRegionProperty

void SetRegionProperty (string key, string value);

Stores a key/value pair in the Regions semi-permanent memory. Will be erased when all players exit the shard, but will persist as long as the shard lives. Subject to rate limiting (12/second on the main grid and 24/second on white-label grids)

Space.Network.SetRegionProperty("testKey", "Test Value") 

 --this script is a networked and persistent color changing of an object
--note that we put the object's GlobalID in the key to make it specific to this object

thisObject = Space.Host.ExecutingObject
currentColor = nil

OnClick = function() --this writes to the region properties
if currentColor == Color.Blue then
  Space.Network.SetRegionProperty(thisObject.GlobalID .. "color", "red")
else
  Space.Network.SetRegionProperty(thisObject.GlobalID .. "color", "blue")
end
  
end

Sync = function() -- this gets from the region properties
  while true do
    local result = Space.Network.GetRegionProperty(thisObject.GlobalID .. "color")
    if result == "red" then
      currentColor = Color.Red 
    else 
      currentColor = Color.Blue
    end

    thisObject.Renderer.Material.SetColor("_Color", currentColor)  
    coroutine.yield(0.1) --to make sure it doesn't run more than 12/second
  end
end


thisObject.AddClickable()
thisObject.Clickable.OnClick(OnClick)
Space.Host.StartCoroutine(Sync)

GetRegionProperty

string GetRegionProperty (string key);

Retrieves the last set value for 'key' in this region. If you have just joined the region, this may not be populated immedietely.

 result = Space.Network.GetRegionProperty("testKey")

--this script is a networked and persistent color changing of an object
--note that we put the object's GlobalID in the key to make it specific to this object

thisObject = Space.Host.ExecutingObject
currentColor = nil

OnClick = function() --this writes to the region properties
if currentColor == Color.Blue then
  Space.Network.SetRegionProperty(thisObject.GlobalID .. "color", "red")
else
  Space.Network.SetRegionProperty(thisObject.GlobalID .. "color", "blue")
end
  
end

Sync = function() -- this gets from the region properties
  while true do
    local result = Space.Network.GetRegionProperty(thisObject.GlobalID .. "color")
    if result == "red" then
      currentColor = Color.Red 
    else 
      currentColor = Color.Blue
    end

    thisObject.Renderer.Material.SetColor("_Color", currentColor)  
    coroutine.yield(0.1) --to make sure it doesn't run more than 12/second
  end
end


thisObject.AddClickable()
thisObject.Clickable.OnClick(OnClick)
Space.Host.StartCoroutine(Sync)

Properties

HasShardProperties

bool HasShardProperties { get; }

Returns True upon successful connection to the Region/Shard properties' storage. Region/Shard property operations may not be ready when used during initialization and this function ill help determine readiness.

IsReady = Space.Network.HasShardProperties

--This script starts but launches a coroutine that waits for HasShardProperties before continuing

DoWhatYouNeed = function(result)
     if property == nil or property == "" then 
Space.Log("connected but Shard doesn't exist")
      else
Space.Log("connected and Shard exists. Result: " .. tostring(result))
      end 
  
  
end


InitCoroutine = function()
    while not Space.Network.HasShardProperties do 
      coroutine.yield(0) 
    end
    
    local property = Space.Network.GetRegionProperty("A Key")
     DoWhatYouNeed(property)
     
end


Space.Host.StartCoroutine(InitCoroutine)