wiki.sine.space | sinespace

Difference between revisions of "Scripting/SNetwork"

From wiki.sine.space
Jump to: navigation, search
m
Line 4: Line 4:
  
 
==Members==
 
==Members==
 +
 +
{{ScriptFunction|void|SubscribeToNetwork|(string key, Action<SNetworkMessage> callback);|Subscribes to network messages on 'key', will fire a [[Scripting/SNetworkMessage]] whenever a matching message is received|5=local scriptedObject = Space.Host.ExecutingObject;<br>
 +
local textValue = Space.Host.GetReference("Text");<br>
 +
scriptedObject.SubscribeToEvents();<br><br>
 +
<i>-- This function gets used by other objects that are subscribed to the network</i><br>
 +
gotAMessage = function(arguments)<br>
 +
&nbsp;&nbsp;textValue.UIText.Text = "Got a message with the argument " .. arguments.Message["someArgument"];<br>
 +
end<br><br>
 +
<i>-- This function gets used by "this" object. Plus, it sends out a message to objects on the network.</i><br>
 +
local updateTextUI = function()<br>
 +
&nbsp;&nbsp;textValue.UIText.Text = "Got a message with the argument Hi there!";<br>
 +
&nbsp;&nbsp;Space.Network.SendNetworkMessage("helloworld", {someArgument = "Hi there!"});<br>
 +
end<br><br>
 +
<i>-- Subscribe to network. Note that "this" object doesn't execute gotAMessage.<br>
 +
-- Only the other objects on the network do.</i><br>
 +
<b>Space.Network.SubscribeToNetwork</b>("helloworld", gotAMessage);<br><br>
 +
scriptedObject.OnMouseDown(updateTextUI);<br><br>
 +
<i>-- "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.</i>}}
 +
 
{{ScriptFunction|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)<br><br>
 
{{ScriptFunction|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)<br><br>
 
This is a modified version of the example for *.Renderer.Material.SetTexture that demonstrates networking.<br><br>note that this example applies also to SubscribeToNetwork.|5 = image = "mrlee.jpg"
 
This is a modified version of the example for *.Renderer.Material.SetTexture that demonstrates networking.<br><br>note that this example applies also to SubscribeToNetwork.|5 = image = "mrlee.jpg"
Line 50: Line 69:
 
<i>-- "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.</i>}}
 
<i>-- "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.</i>}}
  
{{ScriptFunction|void|SubscribeToNetwork|(string key, Action<SNetworkMessage> callback);|Subscribes to network messages on 'key', will fire a [[Scripting/SNetworkMessage]] whenever a matching message is received|5=local scriptedObject = Space.Host.ExecutingObject;<br>
+
 
local textValue = Space.Host.GetReference("Text");<br>
+
scriptedObject.SubscribeToEvents();<br><br>
+
<i>-- This function gets used by other objects that are subscribed to the network</i><br>
+
gotAMessage = function(arguments)<br>
+
&nbsp;&nbsp;textValue.UIText.Text = "Got a message with the argument " .. arguments.Message["someArgument"];<br>
+
end<br><br>
+
<i>-- This function gets used by "this" object. Plus, it sends out a message to objects on the network.</i><br>
+
local updateTextUI = function()<br>
+
&nbsp;&nbsp;textValue.UIText.Text = "Got a message with the argument Hi there!";<br>
+
&nbsp;&nbsp;Space.Network.SendNetworkMessage("helloworld", {someArgument = "Hi there!"});<br>
+
end<br><br>
+
<i>-- Subscribe to network. Note that "this" object doesn't execute gotAMessage.<br>
+
-- Only the other objects on the network do.</i><br>
+
<b>Space.Network.SubscribeToNetwork</b>("helloworld", gotAMessage);<br><br>
+
scriptedObject.OnMouseDown(updateTextUI);<br><br>
+
<i>-- "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.</i>}}
+
  
 
{{ScriptFunction|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)|5=<pre>Space.Network.SetRegionProperty("testKey", "Test Value") </pre>| 6= <pre> --this script is a networked and persistent color changing of an object
 
{{ScriptFunction|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)|5=<pre>Space.Network.SetRegionProperty("testKey", "Test Value") </pre>| 6= <pre> --this script is a networked and persistent color changing of an object

Revision as of 08:32, 22 November 2021

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


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)