efficiency-nodes-comfyui/.github/copilot-instructions.md

Copilot Instructions for efficiency-nodes-comfyui

Project Overview

This repository contains Efficiency Nodes for ComfyUI — a collection of custom nodes for ComfyUI that streamline AI image generation workflows and reduce total node count. The project is maintained by jags111 and is a fork/continuation of the original work by Luciano Cirino.

Repository Structure

efficiency-nodes-comfyui/
├── efficiency_nodes.py      # Main file containing all node class definitions
├── tsc_utils.py             # Utility functions (model caching, loading, helpers)
├── __init__.py              # Package entry point, registers WEB_DIRECTORY and exports
├── pyproject.toml           # Project metadata and ComfyUI registry config
├── requirements.txt         # Python dependencies
├── arial.ttf                # Font used for image annotation nodes
├── node_settings.json       # Default node settings
├── py/                      # Helper modules (samplers, encoders, upscalers)
│   ├── bnk_adv_encode.py    # Advanced CLIP text encoding
│   ├── bnk_tiled_samplers.py
│   ├── city96_latent_upscaler.py
│   ├── smZ_cfg_denoiser.py
│   └── ...
├── js/                      # Frontend JavaScript for ComfyUI web interface
│   ├── appearance.js        # Node color themes
│   ├── seedcontrol.js       # Seed widget behavior
│   ├── widgethider.js       # Dynamic widget visibility
│   └── node_options/        # Right-click context menu additions
└── workflows/               # Example workflow JSON files

Architecture & Key Conventions

Node Class Pattern

All nodes follow the ComfyUI node pattern:

class TSC_MyNode:
    @classmethod
    def INPUT_TYPES(cls):
        return {
            "required": { "param": ("TYPE", {"default": value}) },
            "optional": { "opt_param": ("TYPE",) },
            "hidden":   { "my_unique_id": "UNIQUE_ID" }
        }

    RETURN_TYPES = ("TYPE1", "TYPE2",)
    RETURN_NAMES = ("name1", "name2",)
    FUNCTION = "execute_method"
    CATEGORY = "Efficiency Nodes/Category"

    def execute_method(self, param, opt_param=None, my_unique_id=None):
        # implementation
        return (result1, result2,)

• All node classes are prefixed with TSC_
• FUNCTION must match the name of the method that executes the node
• CATEGORY uses the "Efficiency Nodes/..." namespace for grouping in the ComfyUI UI
• Nodes with side effects (saving images, printing) should set OUTPUT_NODE = True

Node Registration

Nodes are registered at the bottom of efficiency_nodes.py by updating NODE_CLASS_MAPPINGS:

NODE_CLASS_MAPPINGS = {
    "KSampler (Efficient)": TSC_KSampler,
    "Efficient Loader": TSC_EfficientLoader,
    # ...
}

Optional features (requiring extra packages like simpleeval or animatediff) are wrapped in try/except ImportError blocks and registered conditionally.

Model Caching (tsc_utils.py)

The loaded_objects and last_helds globals in tsc_utils.py implement a caching layer to avoid reloading models between node executions:

• loaded_objects["ckpt"] — checkpoints
• loaded_objects["lora"] — LoRA weights
• loaded_objects["vae"] — VAE models
• last_helds["latent"] / last_helds["image"] — KSampler output caches

Always call globals_cleanup(prompt) at the start of loader nodes to evict stale cache entries.

Frontend JavaScript

• JS files in js/ are served by ComfyUI via WEB_DIRECTORY = "js" in __init__.py
• Extensions are registered with app.registerExtension({ name: "efficiency.<name>", ... })
• Use import { app } from "../../scripts/app.js" for ComfyUI's app object
• Widget helpers (findWidgetByName, addMenuHandler) are in js/node_options/common/utils.js

Dependencies

• Python: torch, PIL (Pillow), numpy, comfy (ComfyUI), folder_paths
• Optional Python: simpleeval (Evaluate nodes), clip_interrogator (CLIP Interrogator node)
• ComfyUI extras: comfy_extras.nodes_align_your_steps, comfy_extras.nodes_gits, comfy_extras.nodes_upscale_model

Development Guidelines

• Do not break the node contract: Changing RETURN_TYPES, RETURN_NAMES, or INPUT_TYPES on existing nodes is a breaking change for saved workflows.
• Cache awareness: When modifying loader nodes, preserve calls to globals_cleanup() and the caching functions (load_checkpoint, load_lora, load_vae).
• Error messages: Use the warning() and error() helpers from tsc_utils.py for consistent console output formatting.
• Optional imports: Wrap any new optional feature dependencies in try/except ImportError and print a warning when the package is missing.
• Node naming: Use the TSC_ prefix for new node classes. Register them in NODE_CLASS_MAPPINGS with a human-readable display name (e.g., "My New Node": TSC_MyNewNode).
• JS extensions: Follow the existing pattern of using app.registerExtension with the "efficiency.<extensionName>" naming convention.

Testing & Validation

There is no automated test suite. Validation is done by loading the nodes in a running ComfyUI instance:

1. Install ComfyUI and place this package in ComfyUI/custom_nodes/efficiency-nodes-comfyui/
2. Start ComfyUI and check the console for import errors
3. Open the ComfyUI web interface and verify nodes appear under the Efficiency Nodes menu category
4. Load example workflows from the workflows/ directory to test node behavior

Publishing

The package is published to the ComfyUI Registry via the GitHub Actions workflow .github/workflows/publish.yml, triggered when pyproject.toml is updated on main. Update the version field in pyproject.toml for each release.