feat: Run pre-GUI hooks in the Cinema 4D render submitter

Wire deadline-cloud's pre-GUI submission hooks into the Cinema 4D
submitter so studios can pre-populate the submit dialog (job
name/description, queue parameters, deadline: job properties) before it
opens, matching the equivalent Maya and Nuke integrations.

Submitter:
- _show_submitter calls run_pre_gui_hooks(PreGuiHookContext(
  bundle_dir=None, submitter_name="cinema4d", ...)) before building
  SubmitJobToDeadlineDialog. C4D has no on-disk bundle at pre-GUI time,
  so hooks come from DEADLINE_HOOKS_DIR only, gated by
  settings.allow_environment_hooks.
- _pre_gui_hook_confirm_callback selects the confirmation callback from
  settings.auto_accept (None to skip the prompt, else
  qt_hook_confirmation) so the branch is unit-testable headless.
- Merged output applied via apply_pre_gui_output; since
  RenderSubmitterUISettings has no .parameters list, name/description
  land on the settings object and every hook parameter flows into the
  dialog's shared parameter values.
- Declined confirmation (DeadlineOperationCanceled) aborts cleanly, and
  falsy hook output is a guarded no-op.
- Bumps the deadline floor to >= 0.60.1 (first release shipping
  deadline.client.ui.pre_gui_hooks).

Tests:
- Unit (test_pre_gui_hooks.py): headless coverage of the DCC-owned
  mapping contract (name/description -> settings, params -> shared
  values, empty/falsy/partial output) and the auto_accept confirm
  callback.
- Integration (test/integ/test_cinema4d.py::test_pre_gui_hook): drives
  the real submitter via xa11y with DEADLINE_HOOKS_DIR + a fixture hook
  and asserts the exported bundle carries the hook output
  (name="PREGUI RAN", description, deadline:priority=88). Adds the
  fixtures/pregui_hooks/ hook and test_cases/pregui_hook/ scene; extra_env
  plumbing + _enable_environment_hooks() enable the env-hook path against
  the mock backend. Validated on a Windows + Cinema 4D 2026 workstation
  (1 passed).

Signed-off-by: Leon Li <2182521+leon-li-inspire@users.noreply.github.com>

Author: leon-li-inspire

pyproject.toml

@@ -30,15 +30,15 @@ classifiers = [
 ]
 
 dependencies = [
-    "deadline[gui] >= 0.59, < 0.61",
+    "deadline[gui] >= 0.60.1, < 0.61",
     "openjd-adaptor-runtime >= 0.7,< 0.10",
     # fonttools is Windows-only due to Cinema 4D technical limitations
     "fonttools >=4.59.2, <4.64; sys_platform == 'win32'",
 ]
 
 [project.optional-dependencies]
 gui = [
-    "deadline[gui] >= 0.59, < 0.61",
+    "deadline[gui] >= 0.60.1, < 0.61",
     "PySide6-Essentials == 6.8.3",  # Use 6.8 to align with VFXP 2026: https://vfxplatform.com/#reference-platform
 ]
 

src/deadline/cinema4d_submitter/cinema4d_render_submitter.py

@@ -15,15 +15,22 @@
 from qtpy import QtWidgets
 from qtpy.QtCore import Qt  # type: ignore[attr-defined]
 
+from deadline.client.config import get_setting, str2bool
 from deadline.client.dataclasses import SubmitterInfo
-from deadline.client.exceptions import DeadlineOperationError
+from deadline.client.exceptions import DeadlineOperationCanceled, DeadlineOperationError
 from deadline.client.job_bundle._yaml import deadline_yaml_dump
 from deadline.client.job_bundle.parameters import JobParameter
 from deadline.client.job_bundle.submission import AssetReferences
 from deadline.client.ui.dialogs.submit_job_to_deadline_dialog import (  # pylint: disable=import-error
     JobBundlePurpose,
     SubmitJobToDeadlineDialog,
 )
+from deadline.client.ui.pre_gui_hooks import (
+    PreGuiHookContext,
+    apply_pre_gui_output,
+    qt_hook_confirmation,
+    run_pre_gui_hooks,
+)
 
 from ._version import version_tuple as adaptor_version_tuple
 from .assets import AssetIntrospector
@@ -111,6 +118,10 @@ def show_submitter():
                 )
             else:
                 w = _show_submitter(temp_dir, None)
+            # _show_submitter returns None when the user declines the pre-GUI hook confirmation
+            # prompt; treat that as a normal cancellation and skip showing the dialog.
+            if w is None:
+                return
             w.setStyleSheet(C4D_STYLE)
             w.exec_()
     except Exception:
@@ -933,6 +944,19 @@ def export_to_temp_folder(temp_dir: str, asset_references: AssetReferences) -> N
     asset_references.input_filenames = temp_assets
 
 
+def _pre_gui_hook_confirm_callback(parent):
+    """Choose the confirmation callback for pre-GUI hooks based on the auto_accept setting.
+
+    Returns ``None`` (run hooks without prompting) when ``settings.auto_accept`` is enabled,
+    otherwise the standard Qt confirmation dialog from ``qt_hook_confirmation``. Kept as a small
+    helper so the auto_accept branch can be unit-tested headlessly.
+    """
+    if str2bool(get_setting("settings.auto_accept")):
+        return None
+
+    return qt_hook_confirmation(parent)
+
+
 def _show_submitter(temp_dir: str, parent=None, f=Qt.WindowType.Tool):  # type: ignore[call-overload]
     """
     Creates and returns a submission dialog for rendering jobs.
@@ -1018,12 +1042,41 @@ def on_create_job_bundle_callback(
             host_requirements,
         )
 
+    shared_parameter_values = {
+        "CondaPackages": conda_packages,
+    }
+
+    # Run pre-GUI hooks so studios can pre-populate dialog fields before it opens. Cinema 4D has
+    # no on-disk job bundle at this point, so hooks are sourced from DEADLINE_HOOKS_DIR only
+    # (bundle_dir=None), gated by settings.allow_environment_hooks. The confirmation prompt is
+    # skipped when auto_accept is set; otherwise the standard dialog is shown.
+    try:
+        pre_gui_output = run_pre_gui_hooks(
+            PreGuiHookContext(
+                bundle_dir=None,
+                job_name=render_settings.name,
+                submitter_name="cinema4d",
+                parameters=dict(shared_parameter_values),
+            ),
+            confirm_callback=_pre_gui_hook_confirm_callback(parent),
+        )
+    except DeadlineOperationCanceled:
+        # The user declined the hook confirmation prompt. This is a normal cancellation, not an
+        # error, so abort opening the submitter silently by returning None; show_submitter skips
+        # the dialog. Without this, the exception would surface as a spurious "Deadline UI launch
+        # failed" error for what is a deliberate "No" click.
+        return None
+    # RenderSubmitterUISettings has no `.parameters` list, so apply_pre_gui_output routes
+    # name/description onto it and every hook parameter into shared_parameter_values.
+    # run_pre_gui_hooks returns {} when no hooks run (and raises DeadlineOperationCanceled, handled
+    # above, if the user declines); `or {}` is defensive against any future contract change so the
+    # common no-hooks path can never pass a falsy value into apply_pre_gui_output.
+    apply_pre_gui_output(pre_gui_output or {}, render_settings, shared_parameter_values)
+
     submitter_dialog = SubmitJobToDeadlineDialog(
         job_setup_widget_type=SceneSettingsWidget,
         initial_job_settings=render_settings,
-        initial_shared_parameter_values={
-            "CondaPackages": conda_packages,
-        },
+        initial_shared_parameter_values=shared_parameter_values,
         auto_detected_attachments=auto_detected_attachments,
         attachments=attachments,
         on_create_job_bundle_callback=on_create_job_bundle_callback,

test/AGENTS.md

@@ -344,6 +344,21 @@ the mock logs `404 NO ROUTE`). Add a `@route`-decorated handler in
 resource data, extend `MockDeadlineScenario` there. Keep DCC-specific launch
 behavior in this repository.
 
+**Pre-GUI hook case (`test_pre_gui_hook`):** this one does *not* use the `_CASES`
+/ golden-bundle model — it's a standalone test asserting only the fields a
+pre-GUI hook owns. A hook fixture lives in `fixtures/pregui_hooks/` (a
+`hooks.yaml`, version `"1.0"`, plus `pregui_hook.py`, which reads the job
+metadata on stdin and emits `name` / `description` / `parameters` as JSON on
+stdout). The test enables `settings.allow_environment_hooks` (so the submitter
+sources `DEADLINE_HOOKS_DIR`) and `settings.auto_accept` (so hooks run without
+the Qt confirmation prompt) in the config the `deadline_farm` fixture wrote,
+points `DEADLINE_HOOKS_DIR` at the fixture via the launch env, Exports, and
+asserts the emitted `name`/`description` reached `template.yaml` and
+`deadline:priority` reached `parameter_values.yaml`. To change what the hook
+injects, edit `pregui_hook.py` and the `_HOOK_*` constants in `test_cinema4d.py`
+together (they're the paired source of truth). It has no `expected/job_bundle/`
+and never renders, so it needs no golden capture and runs on macOS too.
+
 ## Installer Tests
 
 Test the built installer. Requires having run `hatch run installer:build-installer` first.

test/integ/fixtures/pregui_hooks/hooks.yaml

@@ -0,0 +1,10 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# Pre-GUI hook manifest for the Cinema 4D xa11y integ test. Discovered via DEADLINE_HOOKS_DIR
+# (gated by settings.allow_environment_hooks); version "1.0" is the schema the installed
+# deadline-cloud validator accepts. The submitter runs the preGUI hook before the dialog opens.
+version: "1.0"
+preGUI:
+  - command: python
+    args:
+      - pregui_hook.py
+    timeout: 60

test/integ/fixtures/pregui_hooks/pregui_hook.py

@@ -0,0 +1,37 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+"""Pre-GUI hook fixture for the Cinema 4D xa11y integ test.
+
+deadline-cloud runs this as a subprocess before the submitter dialog is built (see
+``deadline.client.ui.pre_gui_hooks.run_pre_gui_hooks``). It receives the job metadata as JSON on
+stdin and returns the merged pre-GUI output as JSON on stdout: ``name`` / ``description`` land on
+the submitter's settings object, and every key under ``parameters`` flows into the dialog's shared
+parameter values (``deadline:priority`` sets the Priority field).
+
+The test asserts the exported job bundle reflects exactly these values, proving the C4D submitter
+wires ``run_pre_gui_hooks`` + ``apply_pre_gui_output`` correctly (PR #480). Keep the emitted values
+in sync with ``expected/job_bundle/`` for the ``pregui_hook`` case.
+"""
+
+import json
+import sys
+
+# Consume the metadata C4D passes on stdin (jobName, parameters, submitterName, ...). We do not
+# branch on it here — the point of the fixture is a deterministic, asserted output — but reading it
+# keeps the subprocess contract honest (a real hook would use it). A malformed/empty stdin is not a
+# failure for this fixture: it still emits the fixed output below, so we deliberately ignore a
+# decode error rather than abort.
+try:
+    json.load(sys.stdin)
+except (json.JSONDecodeError, ValueError):
+    # No usable metadata on stdin; the fixture's output does not depend on it, so continue.
+    pass
+
+output = {
+    "name": "PREGUI RAN",
+    "description": "populated by pre-GUI hook",
+    "parameters": {
+        "deadline:priority": 88,
+    },
+}
+
+json.dump(output, sys.stdout)

test/integ/test_cases/pregui_hook/input/scene.py

@@ -0,0 +1,46 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+"""Build the scene for the pre-GUI hook integ case and save it.
+
+Usage: c4dpy scene.py <scene_dir>
+
+Mirrors the ``cube`` case's scene, but this case never renders (the pre-GUI hook
+test only exports a job bundle and asserts its metadata), so it omits the
+render-data setup. The submitter still needs a saved document with a path, which
+the test's sidecar plugin loads before opening the dialog.
+"""
+
+import os
+import sys
+
+import c4d
+
+
+def main() -> int:
+    if len(sys.argv) < 2:
+        print("usage: c4dpy scene.py <scene_dir>", file=sys.stderr)
+        return 2
+
+    scene_dir = sys.argv[1]
+    os.makedirs(scene_dir, exist_ok=True)
+
+    doc = c4d.documents.GetActiveDocument()
+    doc.Flush()
+
+    cube = c4d.BaseObject(c4d.Ocube)
+    cube[c4d.PRIM_CUBE_LEN] = c4d.Vector(200, 200, 200)
+    cube.SetAbsPos(c4d.Vector(0, 100, 0))
+    doc.InsertObject(cube)
+
+    scene_name = "pregui_hook.c4d"
+    scene_path = os.path.join(scene_dir, scene_name)
+    doc.SetDocumentPath(scene_dir)
+    doc.SetDocumentName(scene_name)
+    c4d.documents.SaveDocument(doc, scene_path, c4d.SAVEDOCUMENTFLAGS_0, c4d.FORMAT_C4DEXPORT)
+    c4d.EventAdd()
+
+    print(f"saved: {scene_path}", flush=True)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())