Scripting: Properties

Properties can be assigned to classes or combined in PropertyGroups and then be used in blender directly.

Several properties can have a subtype set. This defines their appearance.

Most properties can react on changes, like when the value is get, set or updated. These reference functions which are called (aka callbacks).

Properties can be dynamically removed with bpy.props.RemoveProperty.

PointerProperty vs. CollectionProperty

A pointer property points to a (and only one!) property. A collection property is basically an list of properties, where you can add and remove instances of properties.

⚠ All properties define update functions except for CollectionProperty!

import bpy

# Define a property group
class SceneSettingItem(bpy.types.PropertyGroup):
    name: bpy.props.StringProperty(name="Test Property", default="Unknown")
    value: bpy.props.IntProperty(name="Test Property", default=22)
bpy.utils.register_class(SceneSettingItem)

# Pointer Property to that group
bpy.types.Scene.my_settings = bpy.props.PointerProperty(type=SceneSettingItem)
bpy.context.scene.my_settings.name="Spam"

# Collection Property as a list of that group
bpy.types.Scene.my_collection = bpy.props.CollectionProperty(type=SceneSettingItem)
my_item = bpy.context.scene.my_collection.add()
my_item.name = "Eggs"

A pointer property might also point to blender types like objects, textures,... :

my_obj_pointer = PointerProperty(name="My Obj Pointer", type=bpy.types.Object)
my_tex_pointer = PointerProperty(name="My Tex Pointer", type=bpy.types.Texture)

Property Types

These are the more useable types of properties and their definition methods:

Method	Comment	Img
BoolProperty	Defines a bool value, either True or False
FloatProperty	Defines a float value Subtypes: - PERCENTAGE shown with a % character - FACTOR - ANGLE - TIME unit (‘NONE’, ‘LENGTH’, ‘AREA’, ‘VOLUME’,...).
IntProperty	Defines an integer value.
StringProperty	Defines a string value. Can have a subtype as a FILE_PATH A path to a file DIR_PATH A path to a folder FILE_NAME A name of a file PASSWORD A text field only showing stars instead of the actual letters
EnumProperty	Defines a selection of values. Can be dynamically created with a function returning the options array.
BoolVectorProperty	Group of bools. Feasable subtypes: LAYER represented as a grid of buttons, can have any size from 1 to 32 (only even numbers make sense though) XYZ QUATERNION needs size set to a value of 4
FloatVectorProperty	Group of floats. Feasable subtypes: COLOR shows up as a color picker, shoud be restricted to values between 0 and 1 TRANSLATION / XYZ_LENGTH shows up with length units DIRECTION shows up as a light ball VELOCITY shows up with velocity units (like m/s) ACCELERATION shows up with acceleration units (like m/s2) EULER shows up in degrees QUATERNION/ AXISANGLE shows up in radiants (?), need size of 4
IntVectorProperty	Group of integers. Only feasable subtype is "XYZ", then it shows up with X, Y and Z-labels.
PropertyGroup	This is not a property itself, but class to derive a group of properties. You need to use a pointerProperty or CollectionProperty to adress it.
PointerProperty	A pointer to a type or a property group.

Example

This is an example of how to define properties:

import bpy

class MyProperties(bpy.types.PropertyGroup):
    my_string : bpy.props.StringProperty(
        name="Name"
        )

    my_float : bpy.props.FloatProperty(
        name="Size", 
        soft_min=0, 
        soft_max=100
        )

    my_enum : bpy.props.EnumProperty(
        name="Object",
        description="This is an enum demonstration",
        # Items: If icon, then you need the number at the end - doh!
        items=[
            ("OPTION1", "Cube", "Create a cube", "CUBE", 0),
            ("OPTION2", "Sphere", "Create a sphere", "SPHERE", 1),
            None, # creates a spacer
            ("OPTION3", "Suzanne", "Create suzanne, the monkey", "MONKEY", 2)
            ]
        )

    my_bool_vec : bpy.props.BoolVectorProperty(
        name="BoolVec",
        subtype="XYZ"
        # size=32
        )

    my_float_vec : bpy.props.FloatVectorProperty(
        name="FloatVec",
        subtype="XYZ"
        # size=32
        )

Blender API Panel Example