Creating a Simple Library Object

Let’s start by creating a simple bare-bones example. We will be creating a Source so this object will be addable to and appear in our Library.

File Locations

First off, locate the “C:/Program Files/PolyPop/UIX” folder on your computer. This folder is traversed by PolypopLive on startup to discover all the components of the app. So we’ll be creating a special sub-folder inside here where we’ll create all our examples.

1. Under “C:/Program Files/PolyPop/UIX”, create a sub-folder called “SDK Examples”. You should now have “C:/Program Files/PolyPop/UIX/SDK Examples”

2. Inside this folder, create a folder called “Example 1”. You should now have “C:/Program Files/PolyPop/UIX/SDK Examples/Example 1”

3. Finally, create 2 blank text files within this folder:

   1. Example1.uix

   2. Example1.lua

UIX file

The UIX file instructs PolypopLive what type of object is being created and where it should be added to the UI (e.g. the Library’s ‘+' menu, Scene Browser, Go Live panel, etc). For our example, we’ll be creating a Source alert.

Open the “Example1.uix” file you created in your code editor and paste the following code into the file.

Example1.uix

<uix type="Source">
  <name>[SDK Example] Example 1</name>
  <source_type>Alert Generator</source_type>
  <category>Alert Objects</category>
</uix>

Let’s break down the elements:

<uix type="Source">

This line means we are defining this as a Source so thus it will appear in the Library.

  <name>[SDK Example] Example 1</name>

This is the name as it appears in the UI.

  <source_type>Alert Generator</source_type>

This line defines the type of source this is which in turn determines how it's grouped within the Library list.

  <category>Alert Objects</category>

This line means it will be grouped with others with the same category name on the '+' menu itself.

</uix>

This closes the scope.

Lua file

This file contains the actual code that is run that implements our new feature.

Here is the contents of “Example1.lua” in its entirety. Be sure to paste it into the “Example1.lua” file you created.

Example1.lua

------------------------------------------------------------------------------------
--  User changable properties
------------------------------------------------------------------------------------
Instance.properties = properties({
  -- Text
  { name="ExampleProperty", type="Text", value="Test", onUpdate="onExamplePropertyUpdate" },
  -- Property Group
  { name="Alerts", type="PropertyGroup", items={
    -- Alert
      { name="onExampleAlert", type="Alert", args={value="Text"}}
  }}
})

------------------------------------------------------------------------------------
-- onInit(): Called once when object is first loaded
------------------------------------------------------------------------------------
function Instance:onInit()
  print("onInit()")
end

------------------------------------------------------------------------------------
-- onReset(): Called when the global Reset button is pressed
------------------------------------------------------------------------------------
function Instance:onReset()
  print("onReset()")
end

------------------------------------------------------------------------------------
-- onDelete(): Called when the object is deleted by the user
------------------------------------------------------------------------------------
function Instance:onDelete()
  print("onDelete()")
end

------------------------------------------------------------------------------------
-- onShowProperties(): Called when the object's properties are displayed to the user
------------------------------------------------------------------------------------
function Instance:onShowProperties()
  print("onShowProperties()")
end

------------------------------------------------------------------------------------
-- onHideProperties(): Called when the object's properties are hidden
------------------------------------------------------------------------------------
function Instance:onHideProperties()
  print("onHideProperties()")
end

------------------------------------------------------------------------------------
-- onSimulateAlert(): For alert properties, used to simulate alert data
------------------------------------------------------------------------------------
function Instance:onSimulateAlert(alert)
  print("onSimulateAlert(".. alert:getName() .. ")")
end

------------------------------------------------------------------------------------
-- onExamplePropertyUpdate(): Called when the ExampleProperty value changes
------------------------------------------------------------------------------------
function Instance:onExamplePropertyUpdate()
  print("onExamplePropertyUpdate() -> " .. self.properties.ExampleProperty)
end

Now let’s test the new Source.

1. Restart or launch PolypopLive if the app is not running.

2. Open the Library if it's not pinned by clicking the “Open Library” button at the bottom left.

3. Click the large + button under the Library list.

You should now see “[SDK Example] Example 1” located next to the other Alerts.

If you click it, a new item will be added to the Library. This item has single Text property called “Example Property” and an Alert called “onAlert”. You’ll also see that a message is printed when various events occur. For instance:

• “onInit()” is printed when the object is first added

• “onShowProperties()” is printed whenever the properties are shown

• “onHideProperties()” is printed whenever the properties are hidden

• “onReset()” is printed whenever the global Reset button is pressed

• “onDelete()” is printed when you delete the item from the Library

• “onExamplePropertyUpdate()” is printed when you change the value of the Example Property

By examining the code, you should see the functions that correlate to each app event. For now, they each just print a message but it’s in those functions where our functionality can be added.

Note: For this example, all the functions are implemented for instructional purposes. When building real objects, you only need to define the functions you actually care about and can omit the rest. This keeps things tidy and efficient.

For instance, if all we care about is the onInit() function, we would have a very short file comprising of just the onInit() function.

At the way top of the code is the properties section. In here we define the properties that appear on the property inspector. In our case, we have a single Text property called “Example Property” and a Property Group that in turn contains an Alert property called “onAlert”. Notice the “Example Property” line defines an ‘onUpdate’ value that points to our “onExamplePropertyUpdate()” function. This function gets called whenever the value changes.

Our alert property currently doesn’t fire for any reason. Let’s add some code that will cause it to fire whenever the Text changes. Since we already have the text update function ready, we just need to add one line of code that will raise the alert. Here’s the completed onExamplePropertyUpdate() function:

function Instance:onExamplePropertyUpdate()
  print("onExamplePropertyUpdate() -> " .. self.properties.ExampleProperty)

  -- Raise the alert passing in the text value
  self.properties.Alerts.onExampleAlert:raise({value=self.properties.ExampleProperty})

end

Now whenever the “Example Property” changes, our “onExampleAlert” is raised with the Text data being passed through. To test the changes:

1. Ensure the file is saved.

2. Delete the item from the Library.

3. Re-add it. Polypop will load the latest version of the code.

Now try changing the Example Property text value. You should see the alert fire. If you connect the alert to an object that has a Text property (like 2D Text) the text value written should transfer through.