user: How do I use Bpy.Props in Blender? Include parameters, examples, warnings and best practices.

assistant: ointer properties do not support storing references to embedded IDs (e.g. bpy.types.Scene.collection , bpy.types.Material.node_tree ). These should exclusively be referenced and accessed through their owner ID (e.g. the scene or material). bpy.props. RemoveProperty ( cls , attr ) ¶ Removes a dynamically defined property. Parameters : cls ( type ) – The class containing the property (must be a positional argument). attr ( str ) – Property name (must be passed as a keyword). Note Typically this function doesn’t need to be accessed directly. Instead use del cls.attr bpy.props. StringProperty ( * , name = '' , description = '' , translation_context = '*' , default = '' , maxlen = 0 , options = {'ANIMATABLE'} , override = set() , tags = set() , subtype = 'NONE' , update = None , get = None , set = None , get_transform = None , set_transform = None , search = None , search_options = {'SUGGESTION'} ) ¶ Returns a new string property definition. Parameters : name ( str ) – Name used in the user interface. description ( str ) – Text used for the tooltip and api documentation. translation_context ( str ) – Text used as context to disambiguate translations. default ( str ) – initializer string. maxlen ( int ) – maximum length of the string. options ( set [ str ] ) – Enumerator in Property Flag Items . override ( set [ str ] ) – Enumerator in Property Override Flag Items . tags ( set [ str ] ) – Enumerator of tags that are defined by parent class. subtype ( str ) – Enumerator in Property Subtype String Items . update (Callable[[ bpy.types.bpy_struct , bpy.types.Context ], None]) – Function to be called when this value is modified, This function must take 2 values (self, context) and return None. Warning there are no safety checks to avoid infinite recursion. get (Callable[[ bpy.types.bpy_struct ], str]) – Function to be called when this value is ‘read’, and the default, system-defined storage is not used for this property. This function must take 1 value (self) and return the value of the property. Note Defining this callback without a matching set one will make the property read-only (even if READ_ONLY option is not set). set (Callable[[ bpy.types.bpy_struct , str], None]) – Function to be called when this value is ‘written’, and the default, system-defined storage is not used for this property. This function must take 2 values (self, value) and return None. Note Defining this callback without a matching get one is invalid. get_transform (Callable[[ bpy.types.bpy_struct , str, bool], str]) – Function to be called when this value is ‘read’, if some additional processing must be performed on the stored value. This function must take three arguments (self, the stored value, and a boolean indicating if the property is currently set), and return the final, transformed value of the property. Note The callback is responsible to ensure that value limits of the property (min/max, length…) are respected. Otherwise a ValueError exception is raised. set_transform (Callable[[ bpy.types.bpy_struct , str, str, bool], str]) – Function to be called when this value is ‘written’, if some additional processing must be performed on the given value before storing it. This function must take four arguments (self, the given value to store, the currently stored value (‘raw’ value, without any get_transform applied to it), and a boolean indicating if the property is currently set), and return the final, transformed value of the property. Note The callback is responsible to ensure that value limits (min/max, length…) are respected. Otherwise a ValueError exception is raised. search (Callable[[ bpy.types.bpy_struct , bpy.types.Context , str], Iterable[str | tuple[str, str]]]) – Function to be called to show candidates for this string (shown in the UI). This function must take 3 values (self, context, edit_text) and return a sequence, iterator or generator where each item must be: A single string (representing a candidate to display). A tuple-pair of strings, where the first is a candidate and the second is additional information about the candidate. search_options ( set [ str ] ) – Set of strings in: ’SORT’ sorts the resulting items. ’SUGGESTION’ lets the user enter values not found in search candidates. WARNING disabling this flag causes the search callback to run on redraw, so only disable this flag if it’s not likely to cause performance issues. Next Audio System (aud) Previous Application Timers (bpy.app.timers) Copyright &#169; Blender Authors Made with Furo Report issue on this page On this page Property Definitions (bpy.props) Assigning to Existing Classes Operator Example PropertyGroup Example Collection Example Update Example Getter/Setter Example BoolProperty() BoolVectorProperty() CollectionProperty() EnumProperty() FloatProperty() FloatVectorProperty() IntProperty() IntVectorProperty() PointerProperty() RemoveProperty() StringProperty()