Pipeline Configuration¶

K-Pipe has two pipeline types, each with its own config file in the bundle:

Type	Config file	Purpose
Publish	`kpipe-publish.toml`	Four-phase workflow that exports and versions scene data
Load	`kpipe-load.toml`	Ordered sequence of one or more steps that imports a published product into the scene

Both files share the same [pipeline.<key>] structure for top-level metadata, but their step declarations differ.

Publish pipelines¶

Pipeline definition¶

Each pipeline is a TOML table identified by a unique key:

[pipeline.blender_render_review_still]
name        = "Review Still"
dcc         = "blender"
tasks       = ["lighting", "animation"]
product_type = "review_png"
description = "Renders a still image of the active camera"

Field	Required	Description
`name`	yes	Display name shown in the DCC UI
`dcc`	yes	Which DCC runs this pipeline (`blender`, `nuke`, `publisher`, …)
`product_type`	yes	Product type identifier this pipeline publishes
`tasks`	no	List of task names that show this pipeline. Empty list = show for all tasks
`description`	no	Short description shown below the pipeline name in the UI
`layers`	no	Default `true`: the publish UI shows a layer selector that suggests previously published layer names (via `Entity.get_product_layers()`) and accepts new ones; the chosen name is set on `ctx.layer` before the pipeline runs (empty = main layer). Set to `false` for product types without layers

Phases and steps¶

The four phases run in order: collect → validate → extract → integrate.

Each phase is declared as an array of tables. Every entry must have an action key naming the action class to run:

[[pipeline.blender_render_review_still.collect]]
action = "CollectBlenderSingleFrame"

[[pipeline.blender_render_review_still.collect]]
action = "CollectBlenderCamera"

[[pipeline.blender_render_review_still.extract]]
action = "ExtractBlenderRender"
file_format = "PNG"

[[pipeline.blender_render_review_still.integrate]]
action = "IntegrateMedia"
keep_files = true

[[pipeline.blender_render_review_still.integrate]]
action = "IntegrateKitsuImage"
optional = true
enabled_by_default = false

All fields other than action, slot, optional, and enabled_by_default are passed directly to the action's dataclass constructor — see the Action Reference for each action's available fields.

Shared step fields¶

Field	Default	Description
`action`	—	Required. Class name of the action to instantiate
`slot`	`"main"`	Named slot used by this action for input and/or output
`optional`	`false`	If `true`, the Blender UI shows a checkbox to enable/disable the step
`enabled_by_default`	`true`	Initial state of the checkbox when `optional = true`

Settings¶

Settings add UI controls to the publish panel. They are declared under [pipeline.<key>.settings] and their values are accessible inside actions via ctx.settings.

Inline syntax (simple types)¶

[pipeline.blender_render_review_still.settings]
note         = { text = "Note", type = "string", default_value = "" }
use_selected = { text = "Use selected strips", type = "bool", default_value = false }
kitsu_main   = { text = "Set main preview", type = "bool", default_value = false, target = "IntegrateKitsuImage.set_as_main" }

Table syntax (required for `enum`)¶

[pipeline.blender_render_review_still.settings.status]
type          = "enum"
text          = "Kitsu Status"
default_value = ""
values        = [["", "Unchanged"], ["wff", "Waiting for feedback"], ["wfa", "Waiting for approval"]]
target        = "IntegrateKitsuImage.task_status"

Setting fields¶

Field	Description
`type`	One of `string`, `bool`, `int`, `float`, `enum`, `scene`
`text`	Label shown in the UI
`default_value`	Initial value
`values`	(enum only) List of items. Each item is either a plain string (identifier = display name) or a `[identifier, display_name]` pair. An empty-string identifier renders as inactive ("Unchanged") in the dropdown
`target`	Push this setting's value into an action field before the pipeline runs (see below)

Setting types¶

Type	UI control	Notes
`string`	Text input
`bool`	Checkbox
`int`	Integer field
`float`	Float field
`enum`	Dropdown	Requires `values` list
`scene`	Dropdown	Populated with scene names from the DCC at runtime

Targeting action fields¶

The target field on a setting pushes its value directly into a matching action's field before the pipeline runs. This lets you expose action parameters as UI controls without writing custom code.

Format: "ClassName.field_name"

target = "IntegrateKitsuImage.task_status"

To push into multiple actions at once, use an array:

target = ["IntegrateKitsuImage.task_status", "IntegrateKitsuVideo.task_status"]

The setting value is only applied if an action with the matching class name exists in the pipeline — no error is raised if it doesn't.

Full example¶

[pipeline.blender_render_review_still]
name         = "Review Still"
dcc          = "blender"
tasks        = []
product_type = "review_png"
description  = "Renders a still image of the current active camera"

  [pipeline.blender_render_review_still.settings]
  note       = { text = "Note", type = "string", default_value = "" }
  kitsu_main = { text = "Set main preview", type = "bool", default_value = false, target = "IntegrateKitsuImage.set_as_main" }

  [pipeline.blender_render_review_still.settings.status]
  type          = "enum"
  text          = "Kitsu Status"
  default_value = ""
  values        = [["", "Unchanged"], ["wff", "Waiting for feedback"], ["wfa", "Waiting for approval"]]
  target        = "IntegrateKitsuImage.task_status"

  [[pipeline.blender_render_review_still.collect]]
  action = "CollectBlenderSingleFrame"

  [[pipeline.blender_render_review_still.collect]]
  action = "CollectBlenderCamera"

  [[pipeline.blender_render_review_still.extract]]
  action = "ExtractBlenderRender"

  [[pipeline.blender_render_review_still.integrate]]
  action      = "IntegrateMedia"
  remap_frames = true
  keep_files  = true

  [[pipeline.blender_render_review_still.integrate]]
  action             = "IntegrateKitsuImage"
  set_as_main        = true
  optional           = true
  enabled_by_default = false

  [[pipeline.blender_render_review_still.integrate]]
  action = "CleanMedia"

Load pipelines¶

Load pipelines use one or more [[pipeline.<key>.load]] steps instead of the four publish phases. Steps run in the order they are declared — useful for chaining a pre-process action before the main load.

[pipeline.image_blender]
name          = "Image"
dcc           = "blender"
product_types = ["texture", "image", "review_png"]
tasks         = []
description   = "Load images as Blender image datablock"

  [[pipeline.image_blender.load]]
  action = "LoadBlenderMedia"
  source = "FILE"

Additional top-level fields for load pipelines¶

Field	Description
`product_types`	List of product type identifiers this pipeline can load

The load step accepts the same action key and any action-specific fields. See LoadBlenderMedia and LoadBlenderTextureSet for available load actions.

Action loading order¶

Actions are discovered at runtime from three locations. Later entries override earlier ones, so project-level actions can replace built-ins by reusing the same class name:

kpipe/actions/ (in packages/core) — built-in actions, available as soon as import kpipe is called
kpipe_<dcc>/…/actions/ (in packages/<dcc>) — DCC-specific actions, loaded when the DCC extension registers
{KPIPE_ROOT}/actions/ — project-level custom actions, loaded on first pipeline build