blender-syntax-properties
Use when adding custom properties to Blender objects -- BoolProperty, IntProperty, FloatProperty, EnumProperty, PointerProperty, or PropertyGroup. Prevents the common mistake of not using update callbacks (changes not reflected in UI) or returning stale items from dynamic EnumProperty. Covers all bpy.props types, subtypes, units, getters/ setters, and CollectionProperty patterns. Keywords: bpy.props, PropertyGroup, BoolProperty, IntProperty, FloatProperty, EnumProperty, PointerProperty, CollectionProperty, update callback, dynamic enum, add custom property, user input, settings.
- License 许可
- MIT
- 最近更新
- 2026-11-09
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- blender-syntax-properties
- license
- MIT
- metadata
- { "author": "OpenAEC-Foundation", "version": "1.0" }
- description
- Use when adding custom properties to Blender objects -- BoolProperty, IntProperty, FloatProperty, EnumProperty, PointerProperty, or PropertyGroup. Prevents the common mistake of not using update callbacks (changes not reflected in UI) or returning stale items from dynamic EnumProperty. Covers all bpy.props types, subtypes, units, getters/ setters, and CollectionProperty patterns. Keywords: bpy.props, PropertyGroup, BoolProperty, IntProperty, FloatProperty, EnumProperty, PointerProperty, CollectionProperty, update callback, dynamic enum, add custom property, user input, settings.
- compatibility
- Designed for Claude Code. Requires Blender 3.x/4.x/5.x with Python.
02 资源文件 3
- 参考文档references/anti-patterns.md12.6 KB
- 参考文档references/examples.md20.3 KB
- 参考文档references/methods.md14.7 KB
03 SKILL.md 正文
blender-syntax-properties
Quick Reference
Property Type Selection
| Need | Property Type | Python Type |
|---|---|---|
| Toggle/flag | BoolProperty |
bool |
| Count/index | IntProperty |
int |
| Size/factor | FloatProperty |
float |
| Name/path | StringProperty |
str |
| Dropdown/mode | EnumProperty |
str (identifier) |
| Axis toggles (X, Y, Z) | BoolVectorProperty |
tuple[bool, ...] |
| Dimensions | IntVectorProperty |
tuple[int, ...] |
| Color/position/rotation | FloatVectorProperty |
tuple[float, ...] |
| Link to another type | PointerProperty |
Reference to PropertyGroup or ID |
| Dynamic list | CollectionProperty |
List of PropertyGroup items |
Critical Warnings
ALWAYS use Python annotation syntax (: not =) for property declarations in classes.
ALWAYS register sub-PropertyGroups BEFORE parent PropertyGroups — registration order matters.
ALWAYS store dynamic enum callback results in a module-level variable to prevent garbage collection crashes.
ALWAYS set explicit unique integer values in enum items used with ENUM_FLAG or getter/setter patterns.
NEVER modify the property that triggered an update callback — causes infinite recursion.
NEVER define set without a matching get callback — Blender raises an error.
NEVER call operators inside update callbacks — they trigger undo and corrupt state.
NEVER set default on EnumProperty when items is a callback — use default=None or omit it.
Version-Critical Changes
| Version | Change | Impact |
|---|---|---|
| 4.1 | Enum ID properties via id_properties_ui |
Integer custom properties can display as dropdowns |
| 5.0 | property_unset() replaces del obj["prop"] |
RNA properties use separate storage from custom properties |
| 5.0 | get_transform / set_transform callbacks |
Faster alternative to get/set using internal storage |
| 5.0 | IDProperty storage split | bpy.props-defined properties no longer accessible via dict syntax |
Blender 5.0 Property Storage Split
# Blender <5.0: dict access to RNA properties worked
value = obj["my_rna_prop"] # WORKED in 4.x
# Blender 5.0+: dict access BROKEN for bpy.props-defined properties
value = obj["my_rna_prop"] # Returns None or KeyError
# CORRECT in 5.0+: use RNA path
value = obj.my_rna_prop
# Reset property to default (replaces del obj["prop"]):
obj.property_unset("my_rna_prop")
Essential Patterns
Pattern 1: Basic Property Declaration
# Blender 3.x/4.x/5.x: annotation syntax REQUIRED
class MyOperator(bpy.types.Operator):
bl_idname = "object.my_operator"
bl_label = "My Operator"
count: bpy.props.IntProperty(name="Count", default=5, min=1, max=100)
factor: bpy.props.FloatProperty(name="Factor", default=1.0, subtype='FACTOR')
name_input: bpy.props.StringProperty(name="Name", default="Object")
Pattern 2: PropertyGroup Registration
# Blender 3.x/4.x/5.x
class MySettings(bpy.types.PropertyGroup):
enabled: bpy.props.BoolProperty(name="Enabled", default=True)
count: bpy.props.IntProperty(name="Count", default=5, min=1)
scale: bpy.props.FloatProperty(name="Scale", default=1.0, min=0.01)
def register():
bpy.utils.register_class(MySettings)
bpy.types.Scene.my_settings = bpy.props.PointerProperty(type=MySettings)
def unregister():
del bpy.types.Scene.my_settings
bpy.utils.unregister_class(MySettings)
Pattern 3: Nested PropertyGroups
# Blender 3.x/4.x/5.x: registration order is CRITICAL
class SubSettings(bpy.types.PropertyGroup):
value: bpy.props.FloatProperty(name="Value", default=0.0)
class MainSettings(bpy.types.PropertyGroup):
sub: bpy.props.PointerProperty(type=SubSettings)
items: bpy.props.CollectionProperty(type=SubSettings)
active_index: bpy.props.IntProperty()
def register():
bpy.utils.register_class(SubSettings) # FIRST: sub-types
bpy.utils.register_class(MainSettings) # SECOND: parent type
bpy.types.Scene.settings = bpy.props.PointerProperty(type=MainSettings)
def unregister():
del bpy.types.Scene.settings
bpy.utils.unregister_class(MainSettings) # Reverse order
bpy.utils.unregister_class(SubSettings)
Pattern 4: Static EnumProperty
# Blender 3.x/4.x/5.x
# Items: (identifier, name, description[, icon[, number]])
my_mode: bpy.props.EnumProperty(
name="Mode",
items=[
('FAST', "Fast", "Low quality, fast render", 'PLAY', 0),
('MEDIUM', "Medium", "Balanced quality", 'PAUSE', 1),
('HIGH', "High", "High quality, slow render", 'RENDER_STILL', 2),
],
default='MEDIUM',
)
Pattern 5: Dynamic EnumProperty
# Blender 3.x/4.x/5.x
# WARNING: MUST store results to prevent garbage collection crash
_enum_items_cache = [] # Module-level storage REQUIRED
def get_object_items(self, context):
global _enum_items_cache
_enum_items_cache = [
(obj.name, obj.name, f"Select {obj.name}", 'OBJECT_DATA', i)
for i, obj in enumerate(bpy.data.objects)
]
if not _enum_items_cache:
_enum_items_cache = [('NONE', "None", "No objects available", 'ERROR', 0)]
return _enum_items_cache
my_object: bpy.props.EnumProperty(
name="Object",
items=get_object_items,
# default MUST be None or omitted when items is a callback
)
Pattern 6: Update Callback
# Blender 3.x/4.x/5.x
def on_count_changed(self, context):
# SAFE: modify OTHER properties on self
if self.count > 10:
self.warning = "High count may impact performance"
# UNSAFE: do NOT modify self.count here (infinite recursion)
# UNSAFE: do NOT call bpy.ops.* here (undo corruption)
class MySettings(bpy.types.PropertyGroup):
count: bpy.props.IntProperty(
name="Count", default=5, update=on_count_changed,
)
warning: bpy.props.StringProperty()
Pattern 7: Getter/Setter
# Blender 3.x/4.x/5.x
def get_computed(self):
# Compute value on read — no internal storage
return len(bpy.data.objects)
def set_computed(self, value):
# Handle write — must store somewhere if persistence needed
self["_cached_count"] = value
class MySettings(bpy.types.PropertyGroup):
object_count: bpy.props.IntProperty(
name="Object Count",
get=get_computed,
set=set_computed,
)
Pattern 8: Get/Set Transform (Blender 5.0+)
# Blender 5.0+ ONLY: faster than get/set, uses internal storage
def clamp_transform(self, new_value, curr_value, is_set):
"""Transform value before storing."""
return max(0.0, min(new_value, 100.0))
def display_transform(self, curr_value, is_set):
"""Transform value on read."""
return curr_value * 2.0 if is_set else 0.0
class MySettings(bpy.types.PropertyGroup):
clamped: bpy.props.FloatProperty(
name="Clamped",
set_transform=clamp_transform,
get_transform=display_transform,
)
Pattern 9: ENUM_FLAG (Multi-Select)
# Blender 3.x/4.x/5.x: numbers MUST be powers of 2
my_flags: bpy.props.EnumProperty(
name="Axes",
items=[
('X', "X Axis", "Include X axis", 1),
('Y', "Y Axis", "Include Y axis", 2),
('Z', "Z Axis", "Include Z axis", 4),
],
options={'ENUM_FLAG'},
default={'X', 'Z'}, # Default is a SET, not a string
)
Pattern 10: PointerProperty with Poll
# Blender 3.x/4.x/5.x: filter selectable objects
def filter_mesh_objects(self, obj):
return obj.type == 'MESH'
class MySettings(bpy.types.PropertyGroup):
target: bpy.props.PointerProperty(
type=bpy.types.Object,
name="Target",
poll=filter_mesh_objects,
)
Pattern 11: CollectionProperty Operations
# Blender 3.x/4.x/5.x
scene = bpy.context.scene
# Add item
item = scene.my_settings.items.add()
item.name = "New Item"
item.value = 42.0
# Remove by index
scene.my_settings.items.remove(0)
# Move item (from_index, to_index)
scene.my_settings.items.move(0, 2)
# Clear all
scene.my_settings.items.clear()
# Iterate
for item in scene.my_settings.items:
print(item.name, item.value)
# Access by index
first = scene.my_settings.items[0]
# Find by name (returns index or -1)
idx = scene.my_settings.items.find("New Item")
Subtype and Unit Quick Reference
Numeric Subtypes
| Subtype | Applies To | Effect |
|---|---|---|
'NONE' |
All | Default display |
'PIXEL' |
Int/Float | Pixel unit display |
'UNSIGNED' |
Int | Unsigned display |
'PERCENTAGE' |
Float | 0-100% display |
'FACTOR' |
Float | 0.0-1.0 slider |
'ANGLE' |
Float | Radians with degree display |
'TIME' |
Float | Scene-relative time (frames) |
'TIME_ABSOLUTE' |
Float | Absolute time (seconds) |
'DISTANCE' |
Float | Distance in scene units |
'POWER' |
Float | Power unit display |
'TEMPERATURE' |
Float | Temperature display |
Vector Subtypes
| Subtype | Applies To | Effect |
|---|---|---|
'COLOR' |
FloatVector | Linear RGB color picker |
'COLOR_GAMMA' |
FloatVector | Gamma-space color picker |
'TRANSLATION' |
FloatVector | Position in scene units |
'DIRECTION' |
FloatVector | Normalized direction |
'VELOCITY' |
FloatVector | Velocity vector |
'ACCELERATION' |
FloatVector | Acceleration vector |
'EULER' |
FloatVector | Euler rotation (radians) |
'QUATERNION' |
FloatVector | Quaternion rotation (size=4) |
'AXISANGLE' |
FloatVector | Axis-angle rotation (size=4) |
'XYZ' |
FloatVector | Generic XYZ coordinates |
'MATRIX' |
FloatVector | Matrix representation |
String Subtypes
| Subtype | Effect |
|---|---|
'NONE' |
Plain text input |
'FILE_PATH' |
File browser button |
'DIR_PATH' |
Directory browser button |
'FILE_NAME' |
File name field |
'BYTE_STRING' |
Byte string |
'PASSWORD' |
Masked input (***) |
Unit Values (FloatProperty / FloatVectorProperty only)
| Unit | Display |
|---|---|
'NONE' |
No unit |
'LENGTH' |
Scene length unit |
'AREA' |
Area (length²) |
'VOLUME' |
Volume (length³) |
'ROTATION' |
Degrees/radians |
'TIME' |
Scene-relative time |
'TIME_ABSOLUTE' |
Absolute seconds |
'VELOCITY' |
Speed |
'ACCELERATION' |
Acceleration |
'MASS' |
Mass |
'CAMERA' |
Camera distance |
'POWER' |
Power |
'TEMPERATURE' |
Temperature |
Options Flags
| Flag | Applies To | Effect |
|---|---|---|
'HIDDEN' |
All | Hidden from UI, accessible via Python |
'SKIP_SAVE' |
All | Value not saved between operator invocations |
'ANIMATABLE' |
All (default) | Can be keyframed |
'LIBRARY_EDITABLE' |
All | Editable on linked data-blocks |
'PROPORTIONAL' |
Numeric | Proportional editing support |
'TEXTEDIT_UPDATE' |
String | Updates on each keystroke |
'ENUM_FLAG' |
Enum only | Multi-select with power-of-2 values |
Decision Trees
When to Use PointerProperty vs CollectionProperty
Need to reference ONE item?
├── YES → PointerProperty
│ ├── Reference to another PropertyGroup? → type=MyPropertyGroup
│ └── Reference to an ID type? → type=bpy.types.Object (or Material, etc.)
└── NO → Need a LIST of items?
└── YES → CollectionProperty(type=MyPropertyGroup)
└── Track active selection? → Add IntProperty for active_index
When to Use get/set vs get_transform/set_transform
Blender version?
├── <5.0 → Use get/set (only option)
└── >=5.0
├── Need custom storage logic? → Use get/set
└── Only need value transformation?
└── Use get_transform/set_transform (faster, uses internal storage)
When to Use update vs msgbus
Property changes on THIS class?
├── YES → Use update callback on the property
└── NO → Watching EXTERNAL property changes?
└── YES → Use bpy.msgbus.subscribe_rna()
Attachment Points
Properties can be attached to any Blender ID type:
# Per-scene settings
bpy.types.Scene.my_prop = bpy.props.PointerProperty(type=MySettings)
# Per-object settings
bpy.types.Object.my_prop = bpy.props.PointerProperty(type=MySettings)
# Per-material settings
bpy.types.Material.my_prop = bpy.props.FloatProperty(name="Custom")
# Per-mesh settings
bpy.types.Mesh.my_prop = bpy.props.IntProperty(name="Custom")
# Per-bone settings
bpy.types.Bone.my_prop = bpy.props.StringProperty(name="Custom")
# Per-window-manager (session-only, not saved)
bpy.types.WindowManager.my_prop = bpy.props.BoolProperty(name="Temp")
WindowManager properties are session-only — they reset when Blender restarts. Use for temporary UI state.
Reference Links
- references/methods.md — Complete API signatures for all bpy.props types
- references/examples.md — Working code examples for every property pattern
- references/anti-patterns.md — What NOT to do, with explanations
Official Sources
04 同仓库更多 Skills
manimce-best-practices
Trigger when: (1) User mentions "manim" or "Manim Community" or "ManimCE", (2) Code contains `from manim import *`, (3) User runs `manim` CLI commands, (4) Working with Scene, MathTex, Create(), or ManimCE-specific classes. Best practices for Manim Community Edition - the community-maintained Python animation engine. Covers Scene structure, animations, LaTeX/MathTex, 3D with ThreeDScene, camera control, styling, and CLI usage. NOT for ManimGL/3b1b version (which uses `manimlib` imports and `manimgl` CLI).
drawio
Create, edit, replicate, import, and export draw.io diagrams with an offline YAML-first workflow: architecture, network topologies, flowcharts, UML/ER, org charts, Mermaid/CSV conversion, existing .drawio bundles, style presets, themes, and non-publication formula diagrams. For publication figures (paper, thesis, IEEE, camera-ready) use drawio-academic-skills instead.
drawio-academic-skills
Publication-figure overlay for draw.io. Use instead of drawio whenever the diagram is for a paper, thesis, dissertation, journal, conference, IEEE/ACM submission, manuscript, camera-ready, Word/LaTeX figure, or other publication. Applies venue, figure-type, color, caption/legend, formula, and paper-readability gates for architecture, workflow, roadmap, network-topology, and replicated paper figures.
uncertainty-and-units
Tracks physical units and propagates measurement uncertainty in scientific calculations using pint and uncertainties. Use for unit conversion and dimensional checking, GUM uncertainty budgets, Type A and Type B evaluation, coverage factors and expanded uncertainty, Monte Carlo propagation, significant-figure and plus-minus reporting, error propagation through curve fits, CODATA constants, auditing Python code for stripped units or broken uncertainty propagation, and order-of-magnitude plausibility checks using dimensionless groups (Reynolds, Peclet, Damkohler, Knudsen, Biot, Womersley), characteristic scales such as diffusion time or Debye length, and observed magnitude ranges. Trigger on "is this number physically reasonable", "sanity check these units", "what regime is this flow in", or a result that looks off by orders of magnitude.
statistical-analysis
Guided statistical analysis for research data - test selection, assumption checking, effect sizes, power analysis, Bayesian alternatives, and APA-formatted reporting. Use whenever a user wants to compare groups, test a hypothesis, analyze experimental or survey data, check statistical assumptions, compute required sample sizes, or write up results - even if they never name a specific test. Covers t-tests, ANOVA, chi-square, correlation, regression, non-parametric and Bayesian methods. For low-level model APIs, see the statsmodels and pymc skills.
simpy
Builds, inspects, tests, and analyzes bounded process-based discrete-event simulations with SimPy. Use for event scheduling, resource queues, interrupts, monitoring, independent replications, warm-up, and reproducible output analysis.