# SNetwork

## Index

### Functions Index

| Function Name                                                                                                                                                                                                                                                                                                                                                                      |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <p>void <a href="#sendnetworkmessage"><strong>SendNetworkMessage</strong> </a>(string key, Table message, bool serverOnly, bool loopback)<br>void <a href="#sendnetworkmessage"><strong>SendNetworkMessage</strong> </a>(string key, Table message, bool serverOnly)<br>void <a href="#sendnetworkmessage"><strong>SendNetworkMessage</strong> </a>(string key, Table message)</p> |
| void[ **SendNetworkMessageToUser**](#sendnetworkmessagetouser) (string key, Table message, uint userID)                                                                                                                                                                                                                                                                            |
| void [**SubscribeToRegionPropertyUpdate**](#subscribetonetwork) (string key, DynValue onRecieve)                                                                                                                                                                                                                                                                                   |
| void [**SubscribeToNetwork** ](#subscribetonetwork)(string key, DynValue onRecieve)                                                                                                                                                                                                                                                                                                |
| void [**SetRegionProperty** ](#setregionproperty)(string key, string value)                                                                                                                                                                                                                                                                                                        |
| string [**GetRegionProperty** ](#getregionproperty)(string key)                                                                                                                                                                                                                                                                                                                    |
| void [**SetShardProperty** ](#setshardproperty)(string key, string value)                                                                                                                                                                                                                                                                                                          |
| string [**GetShardProperty** ](#getshardproperty)(string key)                                                                                                                                                                                                                                                                                                                      |

### Properties Index

| Property Name                                            | Description                                                                                                                                                                                                        |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| bool [**HasShardProperties** ](#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. |

## Functions

### SendNetworkMessage

void **SendNetworkMessage** (string key, Table message)

void **SendNetworkMessage** (string key, Table message, bool serverOnly)

void **SendNetworkMessage** (string key, Table message, bool serverOnly, bool loopback)

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

<table><thead><tr><th width="210">Parameter</th><th width="149">Type</th><th>Description</th></tr></thead><tbody><tr><td></td><td></td><td></td></tr></tbody></table>

{% tabs %}
{% tab title="Lua" %}

```lua
Space.Network.SendNetworkMessage('AKey', {first = "xyz", second= "abc"})
--or
Space.Network.SendNetworkMessage('AKey', {first = "xyz", second= "abc"}, true)
--or
Space.Network.SendNetworkMessage('AKey', {first = "xyz", second= "abc"}, true, true)
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Lua" %}

```lua
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
```

{% endtab %}
{% endtabs %}

### SendNetworkMessageToUser

void **SendNetworkMessageToUser** (string key, Table message)

*Sends a networked message to a specific user 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)*

<table><thead><tr><th width="198">Parameter</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td></td><td></td><td></td></tr></tbody></table>

{% tabs %}
{% tab title="Lua" %}

```lua
Space.Network.SendNetworkMessageToUser('AKey', {first = "xyz", second= "abc"}, 23123123)
```

{% endtab %}
{% endtabs %}

### SubscribeToRegionPropertyUpdate

void **SubscribeToRegionPropertyUpdate** (string key, DynValue onRecieve)

*Subscribes to region property updates on 'key'.*

<table><thead><tr><th width="134.33333333333331">Parameter</th><th width="163">Type</th><th>Description</th></tr></thead><tbody><tr><td>onRecieve</td><td>Callback Closure</td><td>onRecieve(NetworkPropertyUpdate) will be called when a Region Property is updated.<br>NetworkPropertyUpdate = { Key: "property_name", Message: "property_value" }</td></tr></tbody></table>

{% tabs %}
{% tab title="Lua" %}

```lua
function onRecieve(NetworkPropertyUpdate)
propertyKey = NetworkPropertyUpdate.Key
propertyValue = NetworkPropertyUpdate.Message
end
Space.Network.SubscribeToRegionPropertyUpdate('A Key', onRecieve)
```

{% endtab %}
{% endtabs %}

### SubscribeToNetwork

void **SubscribeToNetwork** (string key, Action< [SNetworkMessageLua ](https://docs.breakroom.tech/scripting/client-scripting-api-reference/types/snetworkmessagelua)> onRecieve)\
void **SubscribeToNetwork** (string key, DynValue onRecieve)

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

| Parameter | Type | Description |
| --------- | ---- | ----------- |
|           |      |             |

{% tabs %}
{% tab title="Lua" %}

```lua
function OnRecieveFunction(SNetworkMessageLua)
--
end
Space.Network.SubscribeToNetwork(OnRecieveFunction)
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Lua" %}

```lua
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.
```

{% endtab %}
{% endtabs %}

### 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 region, but will persist as long as the region is open. Subject to rate limiting (10/second on the main grid and 20/second on white-label grids)*

| Parameter | Type | Description |
| --------- | ---- | ----------- |
|           |      |             |

{% tabs %}
{% tab title="Lua" %}

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

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Lua" %}

```lua
 --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)
```

{% endtab %}
{% endtabs %}

### 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.*

| Parameter | Type | Description |
| --------- | ---- | ----------- |
|           |      |             |

{% tabs %}
{% tab title="Lua" %}

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

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Lua" %}

```lua
--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)
```

{% endtab %}
{% endtabs %}

### 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)*

| Parameter | Type | Description |
| --------- | ---- | ----------- |
|           |      |             |

{% tabs %}
{% tab title="Lua" %}

```lua
local scriptedObject = Space.Host.ExecutingObject;
scriptedObject.SubscribeToEvents();

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

scriptedObject.OnMouseDown(updateTextUI);
```

{% endtab %}
{% endtabs %}

### GetShardProperty

string **GetShardProperty** (string key)

*Gets a previously set key.*

| Parameter | Type | Description |
| --------- | ---- | ----------- |
|           |      |             |

{% tabs %}
{% tab title="Lua" %}

```lua
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);
```

{% endtab %}
{% endtabs %}

## 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.*

{% tabs %}
{% tab title="Lua" %}

```lua
IsReady = Space.Network.HasShardProperties
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Lua" %}

```lua
--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)
```

{% endtab %}
{% endtabs %}