Motion Painter 1.0.0 — User Guide

Motion Painter is a Blender add-on for creating object animation by drawing motion paths directly in the 3D Viewport. A painted stroke becomes an editable Motion Painter guide, and the add-on generates ordinary Blender location and, optionally, rotation keyframes for one or more target objects.

This guide covers Motion Painter 1.0.0 for Blender 4.5 LTS and newer, including Blender 5.2 LTS.

At a glance: select objects, choose a Motion Painter brush, move to the desired start frame, and draw. Refine the result from the Motion Painter sidebar. Use Keep Keys, Remove Path when the animation is finished and you no longer need the procedural guide.

Contents

1. Core concepts
2. Requirements and installation
3. Interface overview
4. First animation: quick start
5. Drawing and selecting targets
6. Viewport tools
7. Paths and target management
8. Brushes and motion modes
9. Motion controls
10. Rotation
11. Stacking and blending paths
12. Output and viewport display
13. Linked Blender curves
14. Practical workflows
15. Animation ownership and editing
16. Troubleshooting and diagnostics
17. Defaults and quick-reference tables
18. Technical behavior

1. Core concepts

Understanding four terms makes the add-on much easier to use.

Guide

A guide or path is the editable Motion Painter representation of a painted stroke or linked Blender curve. It stores raw control points, timing, targets, brush settings, stack behavior, rotation settings, and generated-motion data. The colored line drawn in the viewport is the guide overlay; it is not a Blender object unless it is linked to a real curve.

Target

A target is a Blender object animated by a guide. One guide can affect several objects, and one object can be affected by several guides. Targets keep their relative starting offsets, so a group can move as a formation rather than collapsing to one point unless the chosen brush deliberately pulls it toward the path.

Brush

A brush is a preset containing normal Motion Painter settings. Selecting a brush copies its values into the current path or the defaults for future paths. It is not a separate hidden simulation. After choosing a brush, every exposed value can still be changed.

Changing a brush on an existing path does not automatically enable or disable that path's rotation. The rotation checkbox is deliberately independent.

Generated keys

Motion Painter resolves a guide into standard Blender F-curves. While the guide remains active, those generated keys are managed by Motion Painter and can be rebuilt when the guide, targets, settings, stack order, or linked curve changes. Use Keep Keys, Remove Path to detach the result from Motion Painter while preserving the generated keys.

2. Requirements and installation

Requirements

• Motion Painter version: 1.0.0
• Minimum Blender version: 4.5 LTS
• Also supported: Blender 5.2 LTS
• Tools operate in the 3D Viewport in Object Mode.

Blender versions can display native curve control points differently. That visual difference does not change Motion Painter path generation.

Install from the release ZIP

1. Open Blender.
2. Open Edit > Preferences > Add-ons.
3. Choose Install….
4. Select motion_painter-1.0.0.zip.
5. Enable Motion Painter after installation.
6. Close Preferences.

The release archive uses Blender's extension-package layout: blender_manifest.toml and __init__.py are at the ZIP root. Do not re-wrap it in an extra directory before installing it.

Confirm the installation

In a 3D Viewport:

1. Enter Object Mode.
2. Press N to open the sidebar.
3. Look for the Motion Painter tab.
4. Expand the left toolbar with T and look for the Motion Paint tool group.

If both locations appear, the add-on is registered correctly.

Updating from an earlier version

Install the 1.0.0 package and restart or reload Blender before testing. Motion Painter contains compatibility handling for older stored path and rotation data. Save a backup of important .blend files before upgrading any production scene.

3. Interface overview

Motion Painter appears in six places.

Defaults versus selected-path settings

The sidebar has two editing contexts:

• With no path selected, motion controls are the defaults for paths created afterward.
• With a path selected in the Paths list, motion controls edit that existing path and trigger a rebuild.

This distinction is especially important for rotation. The topbar Rotation toggle controls newly created paths only; the selected path's Rotation toggle controls only that path.

Create section

The top of the sidebar shows the current frame and offers:

• Paint Motion Guide — starts freehand drawing. It is available when targets are selected or Auto Select is enabled; Chosen Surface also requires a configured mesh.
• Create Guide from Curve — converts the selected curve into a linked Motion Painter path.
• A selection-status message indicating the number of selected objects, Auto Select readiness, or that objects need to be selected.
• The latest Motion Painter status message, when one is present.

Motion Guides section

The Motion Guides list is the scene's guide stack. Each row contains:

• Enabled checkbox — includes or excludes the path from animation generation.
• Visible eye — shows or hides the guide overlay.
• Object Motion graph — shows or hides generated target-motion previews for the path.
• Editable path name.
• Guide color.

The header provides stack-order arrows, remove-path, and, when several paths exist, remove-all controls.

4. First animation: quick start

This example creates a simple follow-path animation.

1. Add or choose an object in the scene.
2. In Object Mode, select the object.
3. Move the timeline to the frame where motion should start.
4. In the 3D Viewport toolbar, choose Motion Paint.
5. In the topbar, choose the Follow brush.
6. Leave Placement on View-plane and Advance enabled.
7. Press and drag the left mouse button to draw a path.
8. Release the mouse button to create the guide and generate keys.
9. Play the timeline.

The selected object should move along a trajectory derived from the stroke. With Advance enabled, the playhead moves to the generated final frame after creation.

To refine the result:

1. Open the 3D Viewport sidebar with N.
2. Open the Motion Painter tab.
3. Select the guide in Paths.
4. Change Speed, Smooth, or another setting.
5. Scrub or play the timeline to inspect the rebuilt animation.

To finish:

• Leave the guide in the scene if you want continued procedural editing.
• Choose Keep Keys, Remove Path if the motion is approved and you want ordinary editable keys without the guide.

5. Drawing and selecting targets

Using selected objects

With Auto Select off, all currently selected objects become targets when drawing begins. Their starting world transforms are captured so generated motion can be baked correctly, including for parented objects.

Choose this method when the affected objects are known in advance or when nearby objects must not be included accidentally.

Using Auto Select

With Auto Select enabled, Motion Painter finds eligible objects near the start of the stroke. The selection can be evaluated in one of two ways:

The radius preview shows which objects are eligible before the stroke is committed. While using radius selection, use the mouse wheel to change the radius; hold Shift for finer adjustment. Ordinary view navigation remains available when the tool is not in the middle of a freehand stroke.

The nearest eligible object at the stroke-start cursor also supplies View-plane depth and Surface Projection fallback depth. The preview and final stroke share the same resolved depth. A previously selected but unrelated object therefore cannot pull the new path onto the wrong plane.

If no eligible objects are found, the path is cancelled and the original Blender selection and active object are restored.

Hierarchy Roots and painting limits

Hierarchy Roots is enabled by default with Auto Select and appears as Roots in the topbar. If the brush includes a parent and descendants, only the highest included ancestor is animated. Parents outside the brush are not added. Disable it to target individual parts; manual selection is unaffected.

The viewport header shows the full Auto Select target count and a warning above 256 targets. Preview markers are limited to 256 objects per group. New guides are rejected if they exceed 256 targets, 100,000 estimated target-frames across enabled guides and the new stroke, or 4,000 estimated parent-frame evaluations. The estimates include gaps between guides and both location and rotation passes for parents.

If warned, select fewer objects or hierarchy roots, shorten the stroke, or increase speed. Rejected strokes restore the previous selection; they do not animate a partial selection. Baking is synchronous, so these safeguards limit work rather than guarantee a particular response time.

Placement modes

Placement is captured as 3D data. Changing the viewport after creation does not flatten or re-project an existing path.

Spacing

Spacing (px) is the minimum screen-space distance before another freehand point is recorded. A low value records more detail; a high value produces a sparser guide. Because it is measured in pixels, density remains predictable across scene scales and drawing depths.

• Lower spacing is useful for small, intricate gestures.
• Higher spacing is useful for broad, clean motion and reduces raw control-point density.
• Spacing affects guide sampling, while Simplify Keyframes separately controls the number of final output keys.

The default in a new scene is 2 px. Motion Painter always rejects duplicate projected 3D points, even when the pixel threshold is met.

Cancelling a draw

Press Esc or the right mouse button to cancel. Motion Painter removes the temporary preview and restores the selection state from before the tool started. A stroke with fewer than two valid points or no targets is also cancelled.

6. Viewport tools

Motion Paint

Use Motion Paint for continuous freehand paths.

1. Press the left mouse button to start.
2. Drag to record the stroke.
3. Release to generate the guide and animation.

The tool records both point positions and relative draw timing. Draw Speed determines how strongly the final motion preserves those local timing variations.

Motion Polygon

Use Motion Polygon for connected straight or polyline segments.

1. Click to place the first point.
2. Continue clicking to add connected points.
3. Press Enter, Numpad Enter, or Space to finish and generate the animation.
4. Press Esc or the right mouse button to cancel the entire unfinished path.

A live segment previews the next point while the pointer moves. This tool is useful for mechanical routes, corners, and paths that will later be converted to an editable Blender curve.

Motion Eraser

Use Motion Eraser to remove guide control points or nearby path portions.

1. Choose Motion Eraser.
2. Move the cursor over a visible guide to see the eraser radius.
3. Press and drag the left mouse button across points to erase them.
4. Release to finish and rebuild affected motion.
5. Press Esc or the right mouse button during the operation to restore the original path.

If an unlinked guide becomes empty, Motion Painter removes the guide. For a linked curve, erasing updates the source curve while preserving its spline type, handles, NURBS data, cyclic state, material assignment, custom point data, selection state, and unrelated splines. A linked path with fewer than two valid points is considered invalid and its generated animation is cleared.

Motion Select

Choose Motion Select, then click near a visible guide. The nearest guide under the cursor becomes active in the Paths list. If there is no guide under the cursor, the operation reports that no path was found.

Shared drawing settings

Motion Paint and Motion Polygon share the following settings in the topbar and tool-settings region:

7. Paths and target management

Selecting and renaming paths

Click a row in the Paths list or use Motion Select in the viewport. The row name is editable and can be changed without breaking Motion Painter's internal ownership. Motion Painter uses stable identifiers and Blender object references rather than relying only on visible names.

Reordering paths

Use the up and down arrows above the list. Paths higher in the visible list also sit higher in the logical stack. Reordering can change the result when several paths overlap on the same target and frames.

Enabling, hiding, and previewing

These controls are independent:

• Enabled affects generated animation. Disabling a path removes its Motion Painter-owned contribution and rebuilds the stack.
• Visible affects only the guide overlay.
• Object Motion affects only the generated trajectory preview.

Hiding a path therefore does not disable its animation. Conversely, disabling a path does more than merely hide it.

Removing paths

• The X removes the active path and rebuilds Motion Painter-owned animation as needed.
• The Trash button removes all guides when more than one exists.
• Keep Keys, Remove Path retains the final animation and removes the guide plus every guide connected through shared targets. For a connected group, the button reads Keep Keys, Remove N Paths and shows Includes paths sharing targets. Connections can be indirect: if A shares a target with B and B shares another with C, all three are applied together. Unrelated guides remain editable and linked curves remain in the scene.

Removing a guide with a linked curve opens Remove Guide, where Delete Linked Curve defaults to on. The all-guide Remove Guides dialog offers Delete Linked Curves, also on by default when links exist. Turn the option off to keep curve objects while removing the guides and their generated animation. Removing an unlinked individual guide takes effect immediately.

Choose ordinary removal while experimenting. Choose Keep Keys, Remove Path only when you deliberately want to finalize the current result.

Adding or excluding targets

For the active path:

• Select Targets selects all current targets in Blender.
• Add Selected to Path adds selected objects that are not yet targets.
• Exclude Selected removes selected objects from the path.

The sidebar reports missing targets by count and shows up to three cached names. Deleted objects are not replaced automatically by new objects with the same name; add the intended replacement through Add Selected to Path.

These actions use the actual scene selection; Motion Painter does not require a separate editable target list in the panel.

Moving a target before the path begins

If a target is moved or rotated before its path's start frame, Motion Painter can rebase the stored starting transform and rebuild the guide. This lets an animator reposition the setup without recreating the path. Motion Painter monitors target transforms and batches resulting rebuild work.

8. Brushes and motion modes

Built-in brushes

The brush is a starting point. Tune the exposed values for the scale and timing of the scene.

Rail versus Forcefield

Use Rail when exact centerline following matters. Use Forcefield when several objects should respond to the same stroke while maintaining or deliberately modifying their spatial relationship to it.

Preset management

The Motion section provides:

• New Preset — opens a naming dialog and saves the current brush settings in the current .blend file.
• Update Brush — writes current settings back into the selected preset.
• Reset arrow — removes a stored override of a built-in brush and restores its packaged values.
• Trash — deletes a selected custom preset.
• Copy Settings and Paste Settings — transfer brush settings through Motion Painter's internal clipboard.

Custom presets are stored in the scene file. A preset selection writes ordinary values into the path or defaults, so later preset changes do not create an opaque external dependency.

Applying path settings to future paths

When an active path differs from the current creation defaults, Use for New Paths appears in the Apply section. Choose it to copy that path's brush and motion configuration into the defaults for newly drawn paths.

9. Motion controls

The Motion section edits the active path, or future-path defaults when no path is active.

Common controls

Forcefield controls

Advanced Forcefield controls

Expand Advanced under Brush Settings when a difficult curve needs more control.

A useful tuning order

For predictable adjustments, tune in this order:

1. Choose Rail or Forcefield and a nearby brush preset.
2. Set Speed or Rail Duration.
3. Set Smooth until unwanted hand jitter is gone.
4. Shape the lane with Path Pull, Push / Pull, and Reach End.
5. Add Orbit, Wave, or Jitter.
6. Adjust Draw Speed, Turn Slowdown, Acceleration, Speed Up, and Slow Down.
7. Tune rotation after the final trajectory is close, because Follow Direction uses the resolved trajectory.

10. Rotation

Rotation is generated from the final resolved motion after brush effects, stacking, and blending. This is why Follow Direction can correctly follow an orbiting, waving, or blended trajectory rather than merely pointing along the raw painted centerline.

Enabling rotation

• The topbar Rotation checkbox controls paths created afterward.
• The selected path's Rotation section-header checkbox controls the active guide.

When rotation is enabled on a path, Motion Painter captures a starting rotation baseline for each target. Disabling it removes Motion Painter-owned rotation keys and restores the captured baseline. If no enabled guide owns rotation, manual object rotation remains untouched.

Rotation behaviors

Starting Orientation

Use Blend when the object must begin in its authored pose but eventually align to motion. Use Keep Offset when the modeled forward direction or artistic pose should remain offset for the whole path.

Follow Direction controls

• Turning Smoothness softens changes in generated facing direction.
• Bank in Turns adds lean based on trajectory curvature.
• Bank Strength sets the maximum lean.
• Bank Response, under Advanced, changes how rapidly the lean reacts.

Look At Path controls

• Turning Smoothness softens changes in the look direction.
• Nose Axis and Roll Reference, under Advanced, determine the signed local object axes used for orientation.
• Keep Offset is intentionally unavailable.

Spin controls

• Spin Axis chooses local X, Y, or Z.
• Spin Speed is rotations per second. Negative values reverse the direction.

Advanced axis controls

For Look At Path, or Follow Direction with Immediate or Blend:

• Nose Axis supports positive and negative X, Y, and Z. Choose the local axis that visually points out of the object's front.
• Roll Reference supports signed X, Y, and Z and controls which side stays upright around the Nose Axis. It cannot use the same underlying axis as Nose Axis.
• Show Axis Gizmo is available on an active guide. It draws labeled signed X/Y/Z axes on the targets so you can verify the choice in the viewport.
• Additional Rotation applies a final Euler correction after generated orientation.

With Follow Direction and Keep Offset, the axis controls and Show Axis Gizmo are hidden. Advanced shows Keep Offset preserves starting facing. and Adjust facing with Additional Rotation. Use Additional Rotation to adjust that preserved facing.

In Immediate or Blend, if an object points sideways, first correct Nose Axis. Use Additional Rotation for an intentional artistic offset rather than to compensate for an incorrectly selected nose axis.

Rotation continuity

Motion Painter accounts for quaternion sign continuity, Euler compatibility, and axis-angle continuity to avoid flips and unintended long-way interpolation. Compatible path handoffs also pass orientation seeds forward. The rotation simplifier measures angular error separately from location error.

11. Stacking and blending paths

The Stack & Blend section appears when the scene contains more than one guide. Higher list entries have higher priority.

Takeover

Takeover makes the higher path own the target during an overlapping range. Blend Frames creates a smooth handoff from lower motion into the higher path.

Use Takeover for sequential direction changes, switching an object to a new route, or letting one artistic pass replace another.

Add

Add combines the higher guide's flow with motion supplied by lower paths instead of replacing it. Add works as path-flow composition rather than blindly summing unrelated world-space positions.

Use Add for secondary drift, waves, layered direction, or a hand-painted adjustment over a base motion.

Enabled lower paths still matter

An enabled lower path can provide the state from which a higher path begins, even after the higher path takes ownership. A disabled lower path behaves as if it does not exist. This is why disabling a lower guide can change a later guide's starting state.

Overlaps and ownership

Motion Painter resolves all guides for a scene as one stack. It tracks which guide owns each target and frame range, then writes the resolved result. This prevents independently rebuilt guides from leaving duplicate or stale keys.

The Debug section lists blocked ranges when a selected lower path is obscured by a higher path.

Example: base route plus flourish

1. Draw a long Follow path for the base route.
2. Move the timeline to the flourish start frame.
3. Draw a second path affecting the same target.
4. Move the second path above the first.
5. Choose Takeover for a replacement move, or Add for a layered influence.
6. For Takeover, adjust Blend Frames until the handoff is smooth.

12. Output and viewport display

Output & Display settings are global to the scene.

Linear F-Curves

Linear F-Curves writes generated location keys with linear interpolation. Use it for mechanically constant interpolation between keys or when downstream tooling expects linear location curves.

When it is off, Motion Painter writes smooth output and can preserve dense-trajectory tangents through simplification.

Simplify Keyframes

Simplify Keyframes removes unnecessary generated location and rotation keys while keeping the evaluated result inside configured tolerances.

• Max Deviation is the allowed positional difference between dense motion and the simplified location F-curves.
• Max Rotation Deviation is the allowed angular difference for Euler, quaternion, and axis-angle output.

Smaller tolerances keep more keys. Larger tolerances produce cleaner, more editable curves but permit more deviation.

The simplifier validates smooth location and Euler motion against the actual Bezier curves that will be written. Retained location keys inherit tangents from the dense trajectory, helping Slow Down and smooth stops survive reduction without keeping a key on every frame. Quaternion and axis-angle component output uses safe linear interpolation.

Parented targets are simplified in their local animation channels with a parent-scale adjustment to the positional tolerance. Animated parents can require extra keys to preserve the world-space trajectory.

Speed Colors

With Speed Colors enabled, generated target-motion previews use a heatmap:

• Blue represents slower motion.
• Red represents faster motion.
• Color Max Speed sets the speed mapped to the hottest color. Lowering it makes the same motion appear warmer.

Speed colors are based on actual keyed target motion rather than the raw guide alone. The viewport uses a continuous gradient and averages over a short local time window so whole-frame rounding does not create misleading color stripes.

Parented previews sample the parent's animation at each displayed frame and restore the playhead afterward. Interior keyframe, handle, easing, and ancestor-animation edits refresh the preview; expensive sampling runs outside viewport drawing.

Path viewport display

• The overlay icon beside Path Viewport Display makes Motion Painter follow Blender's global Show Overlays state. Disable it when Motion Painter paths should remain visible independently.
• Paths In Front draws paths through objects. Disable it when paths should respect scene depth.
• The 3D Viewport Overlays popover contains Motion Painter Paths, which hides guide, editing, eraser, and axis-gizmo overlays in that viewport.

Time visibility

• Visible Padding is the number of frames before and after the animation range where guides remain fully visible.
• Fade Frames controls the transition before a guide hides farther outside its relevant range.

These settings help keep a scene with many timed paths readable while scrubbing.

Timeline display

Color Guide Keys outlines Motion Painter-owned keys in Timeline and Dope Sheet editors using the contributing guide colors. Additive and coincident ownership can produce multi-color markers. The overlay does not replace or edit Blender's native keys. Minimum Value sets a display-only brightness floor so dark guide colors remain readable.

13. Linked Blender curves

Linked curves provide Blender-native control points for a Motion Painter path.

Create a curve from a path

1. Select a Motion Painter guide in the Paths list.
2. In Curve Link, choose Create 3D Curve.
3. Select the new curve object and enter Edit Mode to adjust it with Blender's curve tools.

The new object is a geometry-free viewport wire: bevel depth, extrusion, and offset are zero. You may add geometry later without changing the link.

Create a path from a curve

1. Select a Blender curve together with the non-curve objects it should animate.
2. In the Motion Painter Create section, choose Create Guide from Curve.
3. Configure targets and motion settings for the new linked path.

Automatic creation while drawing

Enable Linked Curve in Motion Paint or Motion Polygon tool settings. Every new guide is accompanied by a linked Blender curve.

Synchronization

Editing either the curve object or its underlying curve datablock rebuilds the linked Motion Painter animation. Evaluated curve-object and curve-data notifications are matched by name and library and coalesced into a deferred rebuild. Allow the edit to finish so the queued animation update can run.

The curve is treated as raw input. Motion Painter writes raw guide points to the curve and applies smoothing once during generation. It does not write an already-smoothed path and then smooth it again.

NURBS guides use Blender's evaluated centerline and weights rather than the control polygon. Curve bevels and modifiers do not enter that centerline sample. Cyclic polylines include the closing segment. Temporary sampling geometry is removed automatically.

Detach a link

Choose Detach Curve Link. The Motion Painter guide and Blender curve remain in the scene, but changes no longer synchronize. Detaching does not delete either one.

Invalid linked input

A linked curve needs at least two valid points. If editing leaves fewer than two points, Motion Painter clears the generated animation instead of silently reusing stale painted points. Restore valid curve geometry to generate again. A deleted linked curve also invalidates its guide and produces Linked curve is missing in the sidebar. A newly created object with the same name is not silently linked as a replacement.

14. Practical workflows

Animate a formation while preserving spacing

1. Select the formation objects.
2. Choose Follow.
3. Draw the common route.
4. Keep Path Pull near zero to preserve lanes and formation offsets.
5. Raise Path Pull only if the formation should contract toward the centerline.
6. Use Reach End if offset objects lag too far from the endpoint region.

Pull scattered objects onto a route

1. Select the objects or use Auto Select.
2. Choose Path Magnet.
3. Draw the desired centerline.
4. Tune Path Pull for convergence strength.
5. Tune Reach End so the group reaches the route's end region.

Create a precise mechanical route

1. Choose Motion Polygon and the Direct brush.
2. Click route corners.
3. Press Enter to finish.
4. Set Motion Mode to Rail if it is not already selected.
5. Adjust Duration, Spacing, and Smooth.
6. Create a linked 3D curve if exact handle editing is needed.

Build a corkscrew or swarm

1. Select several targets.
2. Choose Orbit or Swirl.
3. Draw a broad centerline.
4. Set Orbit to the desired number of rotations; use a negative value to reverse direction.
5. Set Orbit/Wave Radius, or leave it at zero to derive radius from each target's starting distance.
6. Add Path Pull to contract the swarm, and Jitter for variation.

Create an explosion

1. Place targets around the intended stroke start or use Auto Select.
2. Choose Explosion.
3. Draw the directional gesture.
4. Tune Motion Length and positive Push / Pull.
5. Tune Jitter for breakup.
6. Enable rotation and use Spin for tumbling pieces.

For inward collapse, start with Implosion, which uses an inward radial value.

Make a vehicle follow and bank

1. Draw with Follow or Direct.
2. Enable Rotation on the path.
3. Choose Follow Direction.
4. Choose Immediate or Blend for Starting Orientation, then set the vehicle's correct Nose Axis and Roll Reference under Advanced; use Show Axis Gizmo to verify them in the viewport.
5. Enable Bank in Turns.
6. Tune Bank Strength, then Bank Response.
7. Use Turning Smoothness if orientation reacts too sharply.

Retain an object's opening pose

1. Enable path Rotation.
2. Choose the desired rotation behavior.
3. Set Starting Orientation to Blend.
4. Set Blend Frames for the transition duration.

Use Keep Offset instead when the original orientation should remain a relative offset throughout the whole motion.

Hand off between two motions

1. Create the first path.
2. Move to the handoff frame and create the second path for the same target.
3. Put the second path higher in the Paths list.
4. Set it to Takeover.
5. Adjust Blend Frames.
6. Inspect the Selected Path warnings in Debug if the lower path appears blocked longer than expected.

Finalize for manual Graph Editor work

1. Duplicate or save a backup of the .blend file.
2. Select the approved guide.
3. Check the Apply button's path count. Keep Keys, Remove N Paths includes every guide connected through shared targets.
4. Choose the button to rebuild the final result, keep its keys, and remove that connected group.
5. Edit the retained F-curves normally in Blender. Linked curve objects are retained.

After the guide is removed, Motion Painter no longer rebuilds that path. This is the cleanest handoff from procedural authoring to manual animation editing.

15. Animation ownership and editing

What Motion Painter owns

While guides are active, Motion Painter tracks the location and rotation keys it generated. Cleanup uses recorded action, action slot, channel, and written frame ownership rather than an estimated range or preview samples. Switching the target to another action does not redirect cleanup into that replacement action. Shared actions are copied before generated output is written, protecting other users of the action.

Existing animator-authored keys

If generated motion displaces existing user-authored location or rotation keys, Motion Painter preserves them with their interpolation, handles, easing parameters, keyframe types, and selection state and restores them when its claim is removed. This makes enabling, disabling, deleting, and reordering guides safer for an existing animation.

Location source keys throughout the resolved span, including subframe keys between simplified output keys, are temporarily displaced to prevent distortion. Releasing ownership restores them even when no generated key used their frame.

Still, avoid manually editing keys inside a range that an active guide currently owns: the next rebuild may legitimately replace the guide-owned result. Apply the guide first when manual curve editing should become authoritative.

Stable references

Renaming target objects, guides, or linked curve objects does not normally break ownership because claims use stable path identifiers and Blender object references. Cached names support one-time migration of older files. After initialization, deleting an object leaves a missing reference; an unrelated object reusing the name does not inherit its ownership.

Parented targets

Motion is generated in world space and baked in parent-first order. Location output samples the resolved span and simplifies local channels with a parent-scale adjustment. Rotation evaluates parent transforms at keyed frames and accounts for nonuniform scale, bone parenting, and vertex parenting.

When generated animation is removed from an unkeyed child, its original local offset is restored if the parent binding is unchanged. The child then continues to follow its parent. A changed parent binding uses the saved world-space start converted through the new binding instead of reusing the old local coordinates.

Scene-level rebuilds

Motion Painter rebuilds all affected paths as a scene-owned stack. Guide, timing, and output property edits rebuild synchronously within the same undo step as the setting. Linked-curve and target-transform notifications can defer and coalesce rebuild work. The UI stays focused on the selected guide, but the resolved output accounts for every enabled overlapping guide.

Undo, redo, and failed rebuilds

Undo and redo discard pending work from the abandoned state. Changed procedural inputs, including linked-curve geometry, queue a fresh rebuild; restored manual keys are left alone when procedural inputs are unchanged. Selecting curve handles alone does not count as a geometry edit. Refreshed evaluated poses do not replace the saved original rotation.

If a rebuild fails, Motion Painter restores the previous animation, target transforms, and ownership data. Inspect the status and Debug information to resolve the cause before trying the change again.

16. Troubleshooting and diagnostics

Paint Motion Guide is disabled

Cause: no target is selected and Auto Select is off, or Chosen Surface has no configured mesh.

Fix: select at least one object or enable Auto Select. For Chosen Surface, also choose a mesh in Surface.

The path appears at the wrong depth

Check Placement:

• View-plane uses the active target's depth, or the eligible stroke-start target with Auto Select.
• 3D Cursor uses cursor depth.
• Surface Projection needs visible geometry under the cursor and otherwise falls back to View-plane depth.
• Chosen Surface requires a visible mesh in Surface; adjust Offset if the guide needs separation from the mesh.

If using Auto Select, hover near the intended target before starting. Version 1.0.0 uses the same resolved depth for radius preview and committed stroke.

Auto Select finds nothing

• Increase Radius with the mouse wheel or property field.
• Switch between 3D Space and Screen depending on whether scene depth should matter.
• Confirm the intended objects are eligible and visible in the current view.
• Start the stroke closer to the target cluster.

On cancellation, the original selection should be restored.

The path is too rough

• Increase Smooth.
• Increase drawing Spacing for a cleaner raw guide.
• Convert or link to a Blender curve for deliberate control-point editing.
• Reduce Draw Speed if hand timing creates unwanted pacing changes.

The motion is smooth but has too many keys

• Enable Simplify Keyframes.
• Increase Max Deviation gradually.
• For rotation-heavy motion, adjust Max Rotation Deviation independently.
• Expand Debug and compare dense versus written output-key counts.

Slow Down changes timing unexpectedly

Slow Down intentionally retimes the final part of the motion. In 1.0.0 it should not shorten, reshape, or move the trajectory endpoint. If the endpoint appears different, compare the object trajectory rather than guide visibility, verify no higher stacked path is taking over, and copy a bug report if the issue persists.

An object points sideways or upside down

With Follow Direction and Keep Offset, use Additional Rotation in Advanced to adjust the preserved starting facing. The axis controls are intentionally hidden in this mode.

For Immediate or Blend:

1. Expand Rotation > Advanced.
2. Enable Show Axis Gizmo to inspect the object's signed local axes.
3. Set Nose Axis to the object's modeled forward direction.
4. Set Roll Reference to a different underlying axis that should remain upright.
5. Use Additional Rotation only for a remaining intentional offset.
6. Consider Keep Offset if the original authored orientation should be preserved relatively.

Rotation flips

• Increase Turning Smoothness.
• Check that Nose Axis and Roll Reference do not use the same underlying axis.
• Inspect whether the trajectory reverses or becomes nearly stationary.
• Temporarily reduce orbit, wave, jitter, or aggressive stacking to isolate the source.
• Copy a bug report if a reproducible flip remains; Motion Painter already applies quaternion, Euler, and axis-angle continuity handling.

A lower path seems to do nothing

A higher path may own the same target and frame range. Open Debug and inspect Selected Path Warnings and blocked ranges. Reorder paths, disable the higher path, change its timing, or choose Add if the motions should combine.

Disabling one path changes another path's start

This can be correct. An enabled lower path feeds the state used by a higher path. Disabling it removes that input, so the higher path is resolved from a different starting state.

Editing a linked curve does not rebuild

• Confirm the guide still shows Detach Curve Link, which indicates a live link.
• Ensure the curve contains at least two valid points.
• Make a small curve edit and leave the property interaction so Blender sends the update.
• If necessary, detach and recreate the link.
• Enable Developer Logging and copy a bug report for a reproducible failure.

Version 1.0.0 recognizes updates to either the curve object or its curve datablock and coalesces duplicate notifications.

Old previews appear after opening another file

Version 1.0.0 clears transient viewport, rebuild, target-transform, and modal-tool state on file load, and preview cache keys include the owning scene. If stale data still appears, confirm the installed add-on reports 1.0.0 and reload the add-on or restart Blender.

Debug section

Expand Debug in the sidebar to access:

• Current warnings.
• Copy Bug Report, which copies scene diagnostics, settings, guide data, and warnings.
• A console icon that copies instructions for locating developer logs.
• Last rebuild time, phase, path count, candidate count, and target count.
• Scene frame, selection, guide count, tracked baked frames, and dense-to-written key counts.
• Selected-path point, target, frame, sample, and blocked-range diagnostics.

Enable Developer Logging only while investigating a problem; it prints rebuild, stack, and target diagnostics to Blender's system console.

Useful bug-report checklist

When reporting a reproducible issue, include:

1. Blender version and Motion Painter version.
2. The selected brush and whether the mode is Rail or Forcefield.
3. Placement and Auto Select settings.
4. Number of paths and the relevant stack order/modes.
5. Whether targets are parented.
6. Whether a Blender curve is linked.
7. Steps that reproduce the issue in a small scene.
8. The text from Copy Bug Report and relevant developer-console output.

17. Defaults and quick-reference tables

New-scene defaults

Brush-specific values override shared assumptions where needed to create the preset's characteristic motion.

Drawing input reference

Tool choice

Common control relationships

18. Technical behavior

This section is intended for technical artists, pipeline developers, and anyone diagnosing how a result was produced.

Generation pipeline

At a high level, Motion Painter:

1. Captures raw 3D guide points and optional draw timing.
2. Resolves target starting transforms and offsets.
3. Smooths the path and applies the selected Rail or Forcefield sampling contract.
4. Generates Rail or Forcefield trajectories.
5. Resolves overlapping guides as a scene-level stack.
6. Generates rotation from the resolved trajectory when enabled.
7. Simplifies location and rotation independently within their tolerances.
8. Writes Blender F-curves while tracking ownership and displaced user keys.
9. Records per-guide key ownership for timeline display.
10. Caches guide, motion-preview, and timeline-overlay data for display.

Rail generation

Rail mode follows the centerline directly. Control Points creates a location key from every editable guide point and preserves authored point timing unless turn timing requires denser analysis. Spacing samples by distance. Duration grows when necessary so the requested keys can occupy distinct frames.

Forcefield generation

Forcefield mode builds a centerline and flow basis, then applies target-lane behavior such as contraction, radial displacement, orbit, wave, jitter, endpoint reach, and timing adjustments. Turn Slowdown uses a persistent braking/recovery profile. Speed Up and Slow Down are timing functions over the completed trajectory, not geometry trims.

Rotation generation

Rotation uses the final per-target trajectory after stacking. Follow Direction derives an orientation from motion direction and configured axes, Look At Path points toward the centerline, and Spin accumulates local-axis rotation over time. Starting-orientation logic is applied against captured target baselines.

Key simplification

Location simplification considers position error and trajectory shape. Smooth output is checked against the final Bezier evaluation, including tangents and lateral deviation. Rotation simplification uses angular error so its tolerance is meaningful across rotation representations.

Linked-curve boundary

Linked curves store raw input. Conversions between world-space guide positions and curve-local points occur at the link boundary. Curve edits are read back as raw points, followed by one normal Motion Painter smoothing pass. This prevents double smoothing.

Cache and lifecycle safety in 1.0.0

Viewport preview identities include the owning scene. Opening a different .blend clears preview, timeline, pending rebuild, target-transform, and modal-tool state. Deferred guide and target rebuilds retain their owning scene. Linked-curve dependency updates resolve the updated object or datablock safely and repeated notifications are coalesced.

Source-module map

Version 1.0.0 highlights

• Action and slot ownership, shared-action isolation, and complete source-key restoration protect existing animation.
• Undo and redo keep procedural settings and output consistent; failed rebuilds restore the previous result.
• Parented baking, rotation, local-offset restoration, and previews account for animated parents.
• NURBS and cyclic curve sampling follow the source shape, and linked-curve edits update reliably.
• Applying a guide finalizes its entire connected group of shared-target paths.
• Hierarchy Roots and workload limits keep large target selections manageable.
• Recent guide colors use perceptual separation, and all four viewport tools have custom icons.

Recommended working practice

Keep Motion Painter guides while motion is being designed, save iterations of the .blend file, and use the Debug panel when stack ownership is not obvious. Once a path is approved and direct Graph Editor work should take over, choose Keep Keys, Remove Path. This preserves the editable Blender animation while clearly ending Motion Painter's ownership of that guide.