Engine ¶

Engine()

Animation engine for npblender.

Note: do not instantiate Engine class directly but rather use the single and only instance engine avaiable as global variable in the module.

Engine manages a list of Animations. At each frame change, the compute and view methods of Animations are called.

If subframes is not zero, the compute is called as many times ad defined by this property. This allows more precision in simulations.

Advanced animations can create classes based on [Animation][npblender.animation] or Simulation.

Simple animations can rely on a single function which is passed as argument of engine.go method as shown below:

from npblender import Mesh, engine

# Move a cube of .01 per frame along x
cube = Mesh.cube()
def update():
    cube.points.x += .01
    cube.to_object("Cube")

engine.go(update)

The engine instance of Engine class exposes useful animation properties and methods such as time for current time, delta_time for simulations, is_viewport and rendering to adapt parameters to the context.

Key features

Global animation management (add, run, reset)
Frame stepping with optional subframes
Baking to disk via methods Animation.get_frame_data and [Animation.set_frame_data][npblender.Animation.set_frame_data.
Integration with Blender render/viewport handlers and depsgraph
Support for both viewport updates and render-time updates

Attributes:

Name	Type	Description
`animations`	`list[Animation]`	Global list of registered animations driven by the engine.
`bake_file`	`BakeFile or None`	Active bake file when baking is enabled in the scene, else `None`.
`time_offset`	`float`	Seconds added to the computed time (shifts the timeline origin).
`time_scale`	`float`	Global time scale multiplier (e.g., slow-motion).
`subframes`	`int`	Number of subframes per frame (the engine computes `subframes + 1` steps).
`subframe`	`int`	Current subframe index in `{0, …, subframes}` (`0` means the “main” frame).
`SEED`	`int`	Base RNG seed used to derive per-(frame, subframe) seeds.
`VERBOSE`	`bool`	If `True`, prints per-frame timings to the console.
`STEP_TIMES`	`bool`	If `True`, prints detailed I/O/compute times (load/compute/save/view).

Properties

scene : bpy.types.Scene Active scene (or an overridden scene during handlers). fps : int Frames per second from scene.render.fps. frame : int Current frame number (overridable internally during handlers). is_first_frame : bool True when frame == scene.frame_start. time : float Current time in seconds, including time_offset, time_scale, and subframe. duration : float Timeline duration (seconds) given the current time_scale. delta_time : float Time step between substeps: time_scale / fps / (subframes + 1). rendering : bool True when called from render handlers; False in viewport updates. is_viewport : bool Negation of rendering. use_motion_blur : bool Reflects scene.render.use_motion_blur. is_baked : bool True when a bake file is active (bake_file is not None). frame_seeds : numpy.ndarray Table of per-(frame, subframe) seeds derived from SEED. seed : int Seed for the current (frame, subframe). rng : numpy.random.Generator RNG initialized from seed. depsgraph : bpy.types.Depsgraph Evaluated depsgraph for the current context/update.

Initialize the animation engine.

Sets default scene/frame references, time scaling/offset, subframe parameters, rendering flags, depsgraph cache, and RNG seed table cache.

delta_time `property` ¶

delta_time

Time step between steps or substeps.

Returns:

Type	Description
`float`	`time_scale / fps / (subframes + 1)`.

depsgraph `property` ¶

depsgraph

Evaluated dependency graph.

Returns:

Type	Description
`Depsgraph`	Cached depsgraph during handlers when available, otherwise `bpy.context.evaluated_depsgraph_get()`.

duration `property` ¶

duration

Timeline duration in seconds.

Returns:

Type	Description
`float`	`time_scale * (1 + frame_end - frame_start) / fps`.

fps `property` ¶

fps

Frames-per-second of the active scene.

Returns:

Type	Description
`int`	`scene.render.fps`.

frame `property` ¶

frame

Current frame number.

Returns:

Type	Description
`int`	Cached frame override when set, otherwise `scene.frame_current`.

frame_seeds `property` ¶

frame_seeds

Per-(frame, subframe) RNG seeds table.

Returns:

Type	Description
`numpy.ndarray of dtype uint32, shape (frame_end + 1, subframes + 1)`	A table of deterministic seeds derived from `SEED`. Recomputed when dimensions change or if the cache is invalidated.

is_baked `property` ¶

is_baked

Whether baking is active for the current scene.

Baking is active as soon as it has been defined in the UI.

Returns:

Type	Description
`bool`	`True` if a bake file is active (`bake_file is not None`).

is_first_frame `property` ¶

is_first_frame

Whether the current frame is the timeline start.

Returns:

Type	Description
`bool`	`True` if `frame == scene.frame_start`, else `False`.

is_viewport `property` ¶

is_viewport

Viewport flag (negation of rendering).

Returns:

Type	Description
`bool`	`True` when updating in the viewport.

rendering `property` ¶

rendering

Render-time flag.

Returns:

Type	Description
`bool`	`True` when called from render handlers, else `False`.

rng `property` ¶

rng

Random number generator initialized from seed.

Returns:

Type	Description
`Generator`	Default PCG64 generator seeded with `seed`.

scene `property` ¶

scene

Active Blender scene.

Returns:

Type	Description
`Scene`	The cached scene during handlers if set, otherwise `bpy.context.scene`.

seed `property` ¶

seed

Seed for the current (frame, subframe).

Returns:

Type	Description
`int`	`frame_seeds[frame, subframe]`.

time `property` ¶

time

Current time in seconds.

Subframes are enumerated in the order 1, 2, ..., n-1, 0. The 0 subframe corresponds to the “main” frame computed after substeps.

Note: Time can be controlled with time_offset and time_scale properties.

Returns:

Type	Description
`float`	`time_offset + time_scale * frame / fps`, with `frame` adjusted for subframes when `subframe != 0`.

use_motion_blur `property` ¶

use_motion_blur

Whether motion blur is enabled in the renderer.

Returns:

Type	Description
`bool`	`scene.render.use_motion_blur`.

add ¶

add(animation)

Register an animation to be driven by the engine.

Parameters:

Name	Type	Description	Default
`animation`	`Animation`	An object exposing `reset()`, `compute()`, `view()` and optional baking hooks (`get_frame_data`, `set_frame_data`, `get_frame_state`, `set_frame_state`).	required

animation ¶

animation(animation, subframes=0)

Register and run a single animation (convenience).

Resets the engine with the desired subframes, registers animation, then steps the current frame once.

Parameters:

Name	Type	Description	Default
`animation`	`Animation`	The animation to run.	required
`subframes`	`int`	Number of subframes per frame.	`0`

first_frame_reset ¶

first_frame_reset()

Reset all animations at the first frame.

Calls reset() on each registered animation and logs the reset.

get_evaluated ¶

get_evaluated(spec)

Get an evaluated object from the depsgraph.

Parameters:

Name	Type	Description	Default
`spec`	`str or Object`	Object name or object instance.	required

Returns:

Type	Description
`Object`	The evaluated object (`obj.evaluated_get(depsgraph)`).

go ¶

go(compute, reset=None, view=None, subframes=0)

Run a single animation (convenience).

The animation is defined by the compute function and optionally by reset and view functions.

Parameters:

Name	Type	Description	Default
`compute`	`callable`	Frame/subframe compute function.	required
`reset`	`callable`	Optional first-frame reset function.	`None`
`view`	`callable`	Optional view/update function.	`None`
`subframes`	`int`	Number of subframes per frame.	`0`

init_bake ¶

init_bake()

Initialize or disable baking based on scene properties.

Creates a new [BakeFile][npblender.bakefile.BakeFile] when scene.npblender_use_bake is enabled and a name is set; otherwise clears bake_file.

load_frame ¶

load_frame()

Try to load baked data/state for the current frame.

Returns:

Type	Description
`bool`	`True` if baked animation data (and optional state) were read and applied to all animations; `False` if no bake file or no entry.

reset ¶

reset(subframes=0)

Reset the engine state for a new run.

Clears the animation list, sets the number of subframes, resets the subframe index to 0, and invalidates the cached RNG seed table.

Parameters:

Name	Type	Description	Default
`subframes`	`int`	Number of subframes per frame. The engine will compute `subframes + 1` steps per frame.	`0`

save_frame ¶

save_frame()

Save current animations' data and state to the bake file.

Skips saving unless on the first frame or immediately after the last saved state frame; otherwise writes animations and states for the current frame into bake_file.

step ¶

step()

Advance one frame step (with subframes) and update the view.

Workflow: 1) If first frame, initialize baking. 2) If the frame is baked, load it; otherwise: - On the first frame, call first_frame_reset() and use 0 subframes. - For i in 1..subframes then 0, set subframe and call compute() on each animation. - Save the frame if baking is active. 3) Call view() on each animation.

Notes

Subframe order is 1, 2, …, n-1, 0, where 0 denotes the “main” frame computed after all substeps.

Engine ¶

delta_time property ¶

depsgraph property ¶

duration property ¶

fps property ¶

frame property ¶

frame_seeds property ¶

is_baked property ¶

is_first_frame property ¶

is_viewport property ¶

rendering property ¶

rng property ¶

scene property ¶

seed property ¶

time property ¶

use_motion_blur property ¶

add ¶

animation ¶

first_frame_reset ¶

get_evaluated ¶

go ¶

init_bake ¶

load_frame ¶

reset ¶

save_frame ¶

step ¶

delta_time `property` ¶

depsgraph `property` ¶

duration `property` ¶

fps `property` ¶

frame `property` ¶

frame_seeds `property` ¶

is_baked `property` ¶

is_first_frame `property` ¶

is_viewport `property` ¶

rendering `property` ¶

rng `property` ¶

scene `property` ¶

seed `property` ¶

time `property` ¶

use_motion_blur `property` ¶