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`	Five-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 five phases run in order: collect → validate → config → extract → integrate. Once the pipeline finishes — whether it completed all five phases or an action raised partway through — every action that already ran gets its optional cleanup() called, in reverse order (last action run, first cleaned up).

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.config]]
action = "ConfigBlenderRenderSettings"
file_format = "PNG"

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

[[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_selection = { 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.config]]
  action = "ConfigBlenderRenderSettings"

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

  [[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 five 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