Accessing editing, removing and adding data in your blend file is one of the most important aspects in creating your addons. Because blend files contain a lot of different data it is also one of the more complex areas of scripting. You have to get used to how blender stores and handles data, what types of data exist and how they interact with each other.
With Serpens we try to make this process easier and more visual. That said, it is still something that you will have to work with and understand, especially if you create your own properties which we will go into later.
Blend Data Browser
The Blend Data Browser is our way of visualizing the data in your blend file. You can find the button to open the browser in the Serpens editors header.
You will notice that the browser is opened in the preferences window. You can also open it side by side with your node editor if you prefer that workflow. To go back to the preferences, click the Exit button in the top left corner.
You can find the overall navigation of the browser on the left. Here you also have global filters. The data is displayed on the rest of the window. You can see the name and type of the data and expand items with the arrow button to get the child data of an item.
Sources
Data
This contains most of blenders stored data. You will find objects, images, node groups, materials and so on in here. Most of these are collections. In the case of blender data, a collection just means multiple data items grouped together. There is for example a collection of all objects in your file.
You will use the data source most of the time when you want to find a specific item of some collection, for example a specifically named image or the first object in your file. This is different then what you will use context for.
Context
The context section is where you find data that is relevant for a specific point in time. You can for example get the current active object here or the active scene. This means that when you use this data in Serpens, you will always use the active object. If instead you want to use an object by name go to the data section instead.
The context section is also different because it changes depending on the area you are in. An area is something like the 3D Viewport or the Node Editor. The node editor has an active node tree while the 3D view doesn’t. Therefore the context will be different in each. A lot of items exist in all contexts (like the active object), but there are exceptions.
For these you can copy a context from any area. Simply right click an input field or a button in that area and click the copy context button. This will reload the data in the browser to the data from the context you copied.
App
App contains a few properties relating to your blender install. You can find things like the current blender version here.
Filter Overview
In the filter on the left side of the browser you can filter the data types that are displayed. You can also search for a specific name.
Note that using the filters on the left side of the browser will not filter down the items that are not expanded. It only filters the top level of displayed elements. This is due to blender having a very large amount of data. We might implement workarounds for this at a later point but in the current state this would simply crash blender. You can use the filter buttons on the individual items to filter the elements inside it. Again, this will only filter that level of items.
Discover (Global Search)
The Discover mode is a global search option. It will search all of the items under the Data category. You can use the search bar on the left to filter the results. Here you can separate multiple search options with a comma. Alternatively you can click on the individual segments of the shown results to add or remove them from your search.
This lets you search through the blend data. If you know for example that your property is on an object named “Cube”, just type Cube into the searchbar. This will show all results with this in the path. Now you can click on one of the Cube options to filter down to what you’re looking for and keep searching from there.
This currently has some limitations.
- Only Data is searched so this will not show options from Context.
- While you can search for blend data functions you can not copy them and paste them into a run property function node! As an alternative you can still search for them here and then use the path that is shown in the individual segments to navigate to the same place in the Data category. Then simply copy the function from there.
Properties
If you want to learn more about specific property types or about creating your own properties go here.
Properties are different types of data that live in your blend file. You see these properties as text or number inputs, checkboxes or dropdowns in the blender interface.
Serpens has two ways of using this data in your blend file. As explained above, the blend data browser lets you find data from all over your blend file. On every property you will see a copy button on the right side. This lets you copy this property for use in your node tree. You will be able to get or set the value or even display it in a custom interface.
The second option is to right click an input in the blender interface.
If you know where a specific input can be found, right click it and click Get Serpens Property. This will have the same effect as finding that property in the blend data browser.
It’s important to know that you can’t find all data that you can see in the blend data browser in the UI. Some properties can’t be copied from the input (you will get a warning) and you have to get it from the browser.
Blender Property Node
The blender property node lets you access a copied property in your node tree. After copying the property from the blend data browser or by right clicking an input field, add a blender property node and click the paste property button. This will set up the node for that property.
In this example the name property of an object was copied.
You see that two outputs got added. The first output is a property output. This is used to display the property or access further data from that property. You will see this type of socket on all blend data nodes.
The second output is the value output. This gives you the value of the property.
A good way to think about the different of these outputs is this:
You can use the blend data output to display the property because it represents an actual reference to the object name property.
The value output on the other hand is simply the text (string) that the name currently is set to.
Here you see two blender property nodes that return the object name. One has an input and one doesn’t. This goes back to the Context section explained before.
The node on the left was copied from the Data section, in this case from a specific object named Cube.
The right node was copied from the Context section from the active object.
The node on the left has an input where you can now enter a different object name. The node on the right has no input because it always uses whatever the active object is at that point.
You can use the Shift+V (customizable in the preferences) shortcut to spawn a node with the pasted data path added. This is useful to more quickly add a blender property node after copying a property.
Indexable sockets
You can also see that the Objects input on the left node has a dropdown next to the input field. This can be set to Name, Index or Property.
The default setting in this case is Name. This will use the name you enter to find the data. In this case it’s the name of the object.
Setting the input to Index will use an index to find the object. 0 is the first index, meaning that it will give you the first object in the list of all objects. You can also use negative indices to return from the end of the list of objects meaning that -1 will give you the last object in the list.
Setting the input to Property changes the socket to a blend data input.
This lets you plug in a different object. You could for example use the Objects node to get a specific object or use something like a for loop to go through all objects and get this property for each one of those objects.
Behind Objects you see (Using Active). In some cases this will say No Data instead. Some data types (like Objects) have a default option they will use when nothing is connected to the input. The Objects input will use the active object, the Scenes input will use the active scene. If there is no default you will have to connect the blend data you want to be used to get the property from.
You can do this by using the different blend data input nodes or by copying that blend data from the blend data browser into another blender property node.
Convertible sockets
You can see that you are able to change the data type of the value output socket. You will find this on some input as well as output sockets.
Serpens needs this to be able to automatically convert different data types. If you connect a number to a text input socket Serpens needs to convert it. To properly do this, the right data type needs to be set. When you copy a property this will happen automatically but you will find cases where you have to set this yourself.
Simply set it to the data type that you expect to be returned. In rare cases you will also see a define data type node get added. This happens if you have a data output with no particular type. Data outputs can represent any type so this needs to be defined when plugged into a different data socket so it can be converted if necessary.
Another example of this is when you set a property. For this you first need to connect the property you want to set.
The value input represents what you want to set the property to. Because the object name is a string you will set the input type to string. This also gives you the input field on the input itself.
Property Functions
Property functions are functions that run on a specific property. An example of this would be creating a new image. You are running a function on the images property collection that creates an image.
You copy property functions from the blend data browser. You can use the Functions filter to only see them. Paste the function into a Run Property Function node.
A common point of confusion is where to find the property if an object is selected or not. The expectation would be that this would be a Boolean property (True or False → Selected or Not Selected) on the object.
This property doesn’t exist, you need to use the property functions instead. The reason for this is that the selected property is dependent on what view layer you are on. The property function can take a view layer as an input to give you the expected Boolean for that specific view layer.
You will see that this is input disabled by default. The node will use the active view layer by default if you don’t connect a different one.
You can also see the Require Execute checkbox on the node. If you disable this checkbox you will se the Execute sockets disappear. This is needed to use this property functions node in the interface. Here you don’t have execute sockets and only want the Result output. This would be different if you were creating an image for example. You would want this to happen before and after certain operations which is represented by the execute connections.
Property functions should be used over operators. While you can find a lot of property functions as operators these have downsides.
They work as a “black box”, meaning you don’t know what happens inside them and they don’t return anything. If you use the create image operator you will not get the created image as an output as you would with the property function. Operators also often require a specific context or run on the active item instead of a specific one.
Missing data
A common mistake is displaying a property in the interface for data that doesn’t exist.
In this example the name property for an object named Cube is being displayed.
If there is no object named Cube this will throw an error. You can see this error in the system console.
To avoid this error you need to only display the input if the object named Cube exists.
The general way to display something based on some condition is to use the If/Else Interface node.
You can now toggle the checkbox on the node to display the True or the False output.
We want to control this condition depending on if the object named Cube exists or not.
The best way to do this would be to use the Is Index In Collection node.
With this you can check if a certain index or name can be found in a collection, in this case the collection of all active scene objects.
Serpens provides you with an easier way of doing this as well. You can use the property exists node to check if any property exists. This will check all parts of the property, meaning it will check if there’s an object named Cube as well as if there’s a property called Name on that object.
This is especially useful if you want to display properties with more inputs like the value of a certain nodes input. Here you would have to check if the material exists, if the node with that name exists inside that material and if that node has an input.
Instead this is done with just one node. Be aware that the Property Exists node doesn’t generate the cleanest code, so if you want to edit your generated code after its exported keep this in mind.
Other
Be careful when returning blend data from a function. You can’t return properties, you can only return things like objects where you then access a property on after the function ran. This is a limitation of the blend data socket design right now and might change in the future.