mirror of
https://github.com/Comfy-Org/ComfyUI_frontend.git
synced 2026-01-26 10:59:53 +00:00
docs: Clarify extension terminology and dev server limitations (#5042)
* docs: Clarify extension terminology and dev server limitations * docs: removed unecessary callout to extension docs in main readme, in favor of the contributions.md * docs: remove key points * docs: change docs structure for better semantics and extensibility * docs: add warning emoji * docs: remove mention of 3D core extensions * docs: add feedback in
This commit is contained in:
Simula_r
@@ -61,8 +61,6 @@ Run `npm run prepare` to install Git pre-commit hooks. Currently, the pre-commit
|
||||
|
||||
### Dev Server
|
||||
|
||||
Note: The dev server will NOT load any extension from the ComfyUI server. Only core extensions will be loaded.
|
||||
|
||||
- Start local ComfyUI backend at `localhost:8188`
|
||||
- Run `npm run dev` to start the dev server
|
||||
- Run `npm run dev:electron` to start the dev server with electron API mocked
|
||||
@@ -89,6 +87,10 @@ After you start the dev server, you should see following logs:
|
||||
Make sure your desktop machine and touch device are on the same network. On your touch device,
|
||||
navigate to `http://<server_ip>:5173` (e.g. `http://192.168.2.20:5173` here), to access the ComfyUI frontend.
|
||||
|
||||
> ⚠️ IMPORTANT:
|
||||
The dev server will NOT load JavaScript extensions from custom nodes. Only core extensions (built into the frontend) will be loaded. This is because the shim system that allows custom node JavaScript to import frontend modules only works in production builds. Python custom nodes still function normally. See [Extension Development Guide](docs/extensions/development.md) for details and workarounds. And See [Extension Overview](docs/extensions/README.md) for extensions overview.
|
||||
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Architecture Decision Records
|
||||
|
||||
45
docs/extensions/README.md
Normal file
45
docs/extensions/README.md
Normal file
@@ -0,0 +1,45 @@
|
||||
# ComfyUI Extensions Documentation
|
||||
|
||||
## Overview
|
||||
|
||||
Extensions are the primary way to add functionality to ComfyUI. They can be custom nodes, custom nodes that render widgets (UIs made with javascript), ComfyUI shell UI enhancements, and more. This documentation covers everything you need to know about understanding, using, and developing extensions.
|
||||
|
||||
## Documentation Structure
|
||||
|
||||
- **[Development Guide](./development.md)** - How to develop extensions, including:
|
||||
- Extension architecture and terminology
|
||||
- How extensions load (backend vs frontend)
|
||||
- Why extensions don't work in dev server
|
||||
- Development workarounds and best practices
|
||||
|
||||
- **[Core Extensions Reference](./core.md)** - Detailed reference for core extensions:
|
||||
- Complete list of all core extensions
|
||||
- Extension architecture principles
|
||||
- Hook execution sequence
|
||||
- Best practices for extension development
|
||||
|
||||
## Quick Links
|
||||
|
||||
### Key Concepts
|
||||
|
||||
- **Extension**: Umbrella term for any code that extends ComfyUI
|
||||
- **Custom Nodes**: Python backend nodes (a type of extension)
|
||||
- **JavaScript Extensions**: Frontend UI enhancements
|
||||
- **Core Extensions**: Built-in extensions bundled with ComfyUI
|
||||
|
||||
### Common Tasks
|
||||
|
||||
- [Developing extensions in dev mode](./development.md#development-workarounds)
|
||||
- [Understanding the shim system](./development.md#how-the-shim-works)
|
||||
- [Extension hooks and lifecycle](./core.md#extension-hooks)
|
||||
|
||||
### External Resources
|
||||
|
||||
- [Official JavaScript Extension Docs](https://docs.comfy.org/custom-nodes/js/javascript_overview)
|
||||
- [ComfyExtension TypeScript Interface](../../src/types/comfy.ts)
|
||||
|
||||
## Need Help?
|
||||
|
||||
- Check the [Development Guide](./development.md) for common issues
|
||||
- Review [Core Extensions](./core.md) for examples
|
||||
- Visit the [ComfyUI Discord](https://discord.com/invite/comfyorg) for community support
|
||||
181
docs/extensions/core.md
Normal file
181
docs/extensions/core.md
Normal file
@@ -0,0 +1,181 @@
|
||||
# Core Extensions
|
||||
|
||||
This directory contains the core extensions that provide essential functionality to the ComfyUI frontend.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Overview](#overview)
|
||||
- [Extension Architecture](#extension-architecture)
|
||||
- [Core Extensions](#core-extensions)
|
||||
- [Extension Development](#extension-development)
|
||||
- [Extension Hooks](#extension-hooks)
|
||||
- [Further Reading](#further-reading)
|
||||
|
||||
## Overview
|
||||
|
||||
Extensions in ComfyUI are modular JavaScript modules that extend and enhance the functionality of the frontend. The extensions in this directory are considered "core" as they provide fundamental features that are built into ComfyUI by default.
|
||||
|
||||
## Extension Architecture
|
||||
|
||||
ComfyUI's extension system follows these key principles:
|
||||
|
||||
1. **Registration-based:** Extensions must register themselves with the application using `app.registerExtension()`
|
||||
2. **Hook-driven:** Extensions interact with the system through predefined hooks
|
||||
3. **Non-intrusive:** Extensions should avoid directly modifying core objects where possible
|
||||
|
||||
## Core Extensions List
|
||||
|
||||
The following table lists ALL core extensions in the system as of 2025-01-30:
|
||||
|
||||
### Main Extensions
|
||||
|
||||
| Extension | Description | Category |
|
||||
|-----------|-------------|----------|
|
||||
| clipspace.ts | Implements the Clipspace feature for temporary image storage | Image |
|
||||
| contextMenuFilter.ts | Provides context menu filtering capabilities | UI |
|
||||
| dynamicPrompts.ts | Provides dynamic prompt generation capabilities | Prompts |
|
||||
| editAttention.ts | Implements attention editing functionality | Text |
|
||||
| electronAdapter.ts | Adapts functionality for Electron environment | Platform |
|
||||
| groupNode.ts | Implements the group node functionality to organize workflows | Graph |
|
||||
| groupNodeManage.ts | Provides group node management operations | Graph |
|
||||
| groupOptions.ts | Handles group node configuration options | Graph |
|
||||
| index.ts | Main extension registration and coordination | Core |
|
||||
| load3d.ts | Supports 3D model loading and visualization | 3D |
|
||||
| maskEditorOld.ts | Legacy mask editor implementation | Image |
|
||||
| maskeditor.ts | Implements the mask editor for image masking operations | Image |
|
||||
| nodeTemplates.ts | Provides node template functionality | Templates |
|
||||
| noteNode.ts | Adds note nodes for documentation within workflows | Graph |
|
||||
| previewAny.ts | Universal preview functionality for various data types | Preview |
|
||||
| rerouteNode.ts | Implements reroute nodes for cleaner workflow connections | Graph |
|
||||
| saveImageExtraOutput.ts | Handles additional image output saving | Image |
|
||||
| saveMesh.ts | Implements 3D mesh saving functionality | 3D |
|
||||
| simpleTouchSupport.ts | Provides basic touch interaction support | Input |
|
||||
| slotDefaults.ts | Manages default values for node slots | Nodes |
|
||||
| uploadAudio.ts | Handles audio file upload functionality | Audio |
|
||||
| uploadImage.ts | Handles image upload functionality | Image |
|
||||
| webcamCapture.ts | Provides webcam capture capabilities | Media |
|
||||
| widgetInputs.ts | Implements various widget input types | Widgets |
|
||||
|
||||
|
||||
### Conditional Lines Subdirectory
|
||||
Located in `extensions/core/load3d/conditional-lines/`:
|
||||
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| ColoredShadowMaterial.js | Material for colored shadow rendering |
|
||||
| ConditionalEdgesGeometry.js | Geometry for conditional edge rendering |
|
||||
| ConditionalEdgesShader.js | Shader for conditional edges |
|
||||
| OutsideEdgesGeometry.js | Geometry for outside edge detection |
|
||||
|
||||
### Lines2 Subdirectory
|
||||
Located in `extensions/core/load3d/conditional-lines/Lines2/`:
|
||||
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| ConditionalLineMaterial.js | Material for conditional line rendering |
|
||||
| ConditionalLineSegmentsGeometry.js | Geometry for conditional line segments |
|
||||
|
||||
### ThreeJS Override Subdirectory
|
||||
Located in `extensions/core/load3d/threejsOverride/`:
|
||||
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| OverrideMTLLoader.js | Custom MTL loader with enhanced functionality |
|
||||
|
||||
## Extension Development
|
||||
|
||||
When developing or modifying extensions, follow these best practices:
|
||||
|
||||
1. **Use provided hooks** rather than directly modifying core application objects
|
||||
2. **Maintain compatibility** with other extensions
|
||||
3. **Follow naming conventions** for both extension names and settings
|
||||
4. **Properly document** extension hooks and functionality
|
||||
5. **Test with other extensions** to ensure no conflicts
|
||||
|
||||
### Extension Registration
|
||||
|
||||
Extensions are registered using the `app.registerExtension()` method:
|
||||
|
||||
```javascript
|
||||
app.registerExtension({
|
||||
name: "MyExtension",
|
||||
|
||||
// Hook implementations
|
||||
async init() {
|
||||
// Implementation
|
||||
},
|
||||
|
||||
async beforeRegisterNodeDef(nodeType, nodeData, app) {
|
||||
// Implementation
|
||||
}
|
||||
|
||||
// Other hooks as needed
|
||||
});
|
||||
```
|
||||
|
||||
## Extension Hooks
|
||||
|
||||
ComfyUI extensions can implement various hooks that are called at specific points in the application lifecycle:
|
||||
|
||||
### Hook Execution Sequence
|
||||
|
||||
#### Web Page Load
|
||||
|
||||
```
|
||||
init
|
||||
addCustomNodeDefs
|
||||
getCustomWidgets
|
||||
beforeRegisterNodeDef [repeated multiple times]
|
||||
registerCustomNodes
|
||||
beforeConfigureGraph
|
||||
nodeCreated
|
||||
loadedGraphNode
|
||||
afterConfigureGraph
|
||||
setup
|
||||
```
|
||||
|
||||
#### Loading Workflow
|
||||
|
||||
```
|
||||
beforeConfigureGraph
|
||||
beforeRegisterNodeDef [zero, one, or multiple times]
|
||||
nodeCreated [repeated multiple times]
|
||||
loadedGraphNode [repeated multiple times]
|
||||
afterConfigureGraph
|
||||
```
|
||||
|
||||
#### Adding New Node
|
||||
|
||||
```
|
||||
nodeCreated
|
||||
```
|
||||
|
||||
### Key Hooks
|
||||
|
||||
| Hook | Description |
|
||||
|------|-------------|
|
||||
| `init` | Called after canvas creation but before nodes are added |
|
||||
| `setup` | Called after the application is fully set up and running |
|
||||
| `addCustomNodeDefs` | Called before nodes are registered with the graph |
|
||||
| `getCustomWidgets` | Allows extensions to add custom widgets |
|
||||
| `beforeRegisterNodeDef` | Allows extensions to modify nodes before registration |
|
||||
| `registerCustomNodes` | Allows extensions to register additional nodes |
|
||||
| `loadedGraphNode` | Called when a node is reloaded onto the graph |
|
||||
| `nodeCreated` | Called after a node's constructor |
|
||||
| `beforeConfigureGraph` | Called before a graph is configured |
|
||||
| `afterConfigureGraph` | Called after a graph is configured |
|
||||
| `getSelectionToolboxCommands` | Allows extensions to add commands to the selection toolbox |
|
||||
|
||||
For the complete list of available hooks and detailed descriptions, see the [ComfyExtension interface in comfy.ts](https://github.com/Comfy-Org/ComfyUI_frontend/blob/main/src/types/comfy.ts).
|
||||
|
||||
## Further Reading
|
||||
|
||||
For more detailed information about ComfyUI's extension system, refer to the official documentation:
|
||||
|
||||
- [JavaScript Extension Overview](https://docs.comfy.org/custom-nodes/js/javascript_overview)
|
||||
- [JavaScript Hooks](https://docs.comfy.org/custom-nodes/js/javascript_hooks)
|
||||
- [JavaScript Objects and Hijacking](https://docs.comfy.org/custom-nodes/js/javascript_objects_and_hijacking)
|
||||
- [JavaScript Settings](https://docs.comfy.org/custom-nodes/js/javascript_settings)
|
||||
- [JavaScript Examples](https://docs.comfy.org/custom-nodes/js/javascript_examples)
|
||||
|
||||
Also, check the main [README.md](https://github.com/Comfy-Org/ComfyUI_frontend#developer-apis) section on Developer APIs for the latest information on extension APIs and features.
|
||||
136
docs/extensions/development.md
Normal file
136
docs/extensions/development.md
Normal file
@@ -0,0 +1,136 @@
|
||||
# Extension Development Guide
|
||||
|
||||
## Understanding Extensions in ComfyUI
|
||||
|
||||
### Terminology Clarification
|
||||
|
||||
**ComfyUI Extension** - The umbrella term for any 3rd party code that extends ComfyUI functionality. This includes:
|
||||
|
||||
1. **Python Custom Nodes** - Backend nodes providing new operations
|
||||
- Located in `/custom_nodes/` directories
|
||||
- Registered via Python module system
|
||||
- Identified by `custom_nodes.<name>` in `python_module` field
|
||||
|
||||
2. **JavaScript Extensions** - Frontend functionality that can be:
|
||||
- Pure JavaScript extensions (implement `ComfyExtension` interface)
|
||||
- JavaScript components of custom nodes (in `/web/` or `/js/` folders, or custom directories specified via `WEB_DIRECTORY` export in `__init__.py` [see docs](https://docs.comfy.org/custom-nodes/backend/lifecycle#web-directory))
|
||||
- Core extensions (built into frontend at `/src/extensions/core/` - see [Core Extensions Documentation](./core.md))
|
||||
|
||||
### How Extensions Load
|
||||
|
||||
**Backend Flow (Python Custom Nodes):**
|
||||
1. ComfyUI server starts → scans `/custom_nodes/` directories
|
||||
2. Loads Python modules (e.g., `/custom_nodes/ComfyUI-Impact-Pack/__init__.py`)
|
||||
3. Python code registers new node types with the server
|
||||
4. Server exposes these via `/object_info` API with metadata like `python_module: "custom_nodes.ComfyUI-Impact-Pack"`
|
||||
5. These nodes execute on the server when workflows run
|
||||
|
||||
**Frontend Flow (JavaScript):**
|
||||
|
||||
*Core Extensions (always available):*
|
||||
1. Built directly into the frontend bundle at `/src/extensions/core/`
|
||||
2. Loaded immediately when the frontend starts
|
||||
3. No network requests needed - they're part of the compiled code
|
||||
|
||||
*Custom Node JavaScript (loaded dynamically):*
|
||||
1. Frontend starts → calls `/extensions` API
|
||||
2. Server responds with list of JavaScript files from:
|
||||
- `/web/extensions/*.js` (legacy location)
|
||||
- `/custom_nodes/*/web/*.js` (node-specific UI code)
|
||||
3. Frontend fetches each JavaScript file (e.g., `/extensions/ComfyUI-Impact-Pack/impact.js`)
|
||||
4. JavaScript executes immediately, calling `app.registerExtension()` to hook into the UI
|
||||
5. These registered hooks enhance the UI for their associated Python nodes
|
||||
|
||||
**The Key Distinction:**
|
||||
- **Python nodes** = Backend processing (what shows in your node menu)
|
||||
- **JavaScript extensions** = Frontend enhancements (how nodes look/behave in the UI)
|
||||
- A custom node package can have both, just Python, or (rarely) just JavaScript
|
||||
|
||||
## Why Extensions Don't Load in Dev Server
|
||||
|
||||
The development server cannot load custom node JavaScript due to architectural constraints from the TypeScript/Vite migration.
|
||||
|
||||
### The Technical Challenge
|
||||
|
||||
ComfyUI migrated to TypeScript and Vite, but thousands of extensions rely on the old unbundled module system. The solution was a **shim system** that maintains backward compatibility - but only in production builds.
|
||||
|
||||
### How the Shim Works
|
||||
|
||||
**Production Build:**
|
||||
During production build, a custom Vite plugin:
|
||||
- Binds all module exports to `window.comfyAPI`
|
||||
- Generates shim files that re-export from this global object
|
||||
|
||||
```javascript
|
||||
// Original source: /scripts/api.ts
|
||||
export const api = { }
|
||||
|
||||
// Generated shim: /scripts/api.js
|
||||
export * from window.comfyAPI.modules['/scripts/api.js']
|
||||
|
||||
// Extension imports work unchanged:
|
||||
import { api } from '/scripts/api.js'
|
||||
```
|
||||
|
||||
**Why Dev Server Can't Support This:**
|
||||
- The dev server serves raw source files without bundling
|
||||
- Vite refuses to transform node_modules in unbundled mode
|
||||
- Creating real-time shims would require intercepting every module request
|
||||
- This would defeat the purpose of a fast dev server
|
||||
|
||||
### The Trade-off
|
||||
|
||||
This was the least friction approach:
|
||||
- ✅ Extensions work in production without changes
|
||||
- ✅ Developers get modern tooling (TypeScript, hot reload)
|
||||
- ❌ Extension testing requires production build or workarounds
|
||||
|
||||
The alternative would have been breaking all existing extensions or staying with the legacy build system.
|
||||
|
||||
## Development Workarounds
|
||||
|
||||
### Option 1: Develop as Core Extension (Recommended)
|
||||
|
||||
1. Copy your extension to `src/extensions/core/` (see [Core Extensions Documentation](./core.md) for existing core extensions and architecture)
|
||||
2. Update imports to relative paths:
|
||||
```javascript
|
||||
import { app } from '../../scripts/app'
|
||||
import { api } from '../../scripts/api'
|
||||
```
|
||||
3. Add to `src/extensions/core/index.ts`
|
||||
4. Test with hot reload working
|
||||
5. Move back when complete
|
||||
|
||||
### Option 2: Use Production Build
|
||||
|
||||
Build the frontend for full functionality:
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
For faster iteration during development, use watch mode:
|
||||
```bash
|
||||
npx vite build --watch
|
||||
```
|
||||
|
||||
Note: Watch mode provides faster rebuilds than full builds, but still no hot reload
|
||||
|
||||
### Option 3: Test Against Cloud/Staging
|
||||
|
||||
For cloud extensions, modify `.env`:
|
||||
```
|
||||
DEV_SERVER_COMFYUI_URL=http://stagingcloud.comfy.org/
|
||||
```
|
||||
|
||||
## Key Points
|
||||
|
||||
- Python nodes work normally in dev mode
|
||||
- JavaScript extensions require workarounds or production builds
|
||||
- Core extensions provide built-in functionality - see [Core Extensions Documentation](./core.md) for the complete list
|
||||
- The `ComfyExtension` interface defines all available hooks for extending the frontend
|
||||
|
||||
## Further Reading
|
||||
|
||||
- [Core Extensions Architecture](./core.md) - Complete list of core extensions and development guidelines
|
||||
- [JavaScript Extension Hooks](https://docs.comfy.org/custom-nodes/js/javascript_hooks) - Official documentation on extension hooks
|
||||
- [ComfyExtension Interface](../../src/types/comfy.ts) - TypeScript interface defining all extension capabilities
|
||||
@@ -2,203 +2,27 @@
|
||||
|
||||
This directory contains the core extensions that provide essential functionality to the ComfyUI frontend.
|
||||
|
||||
## Table of Contents
|
||||
## 📚 Full Documentation
|
||||
|
||||
- [Overview](#overview)
|
||||
- [Extension Architecture](#extension-architecture)
|
||||
- [Core Extensions](#core-extensions)
|
||||
- [Extension Development](#extension-development)
|
||||
- [Extension Hooks](#extension-hooks)
|
||||
- [Further Reading](#further-reading)
|
||||
The complete documentation for core extensions has been moved to:
|
||||
|
||||
## Overview
|
||||
**[/docs/extensions/core.md](/docs/extensions/core.md)**
|
||||
|
||||
Extensions in ComfyUI are modular JavaScript modules that extend and enhance the functionality of the frontend. The extensions in this directory are considered "core" as they provide fundamental features that are built into ComfyUI by default.
|
||||
## Quick Reference
|
||||
|
||||
## Extension Architecture
|
||||
This directory contains built-in extensions that ship with ComfyUI, including:
|
||||
|
||||
ComfyUI's extension system follows these key principles:
|
||||
- **Image Processing**: maskeditor, uploadImage, saveImageExtraOutput, clipspace
|
||||
- **Graph Management**: groupNode, groupNodeManage, groupOptions, rerouteNode, noteNode
|
||||
- **Input Handling**: widgetInputs, uploadAudio, webcamCapture, simpleTouchSupport
|
||||
- **UI Enhancements**: contextMenuFilter, previewAny, nodeTemplates
|
||||
- **Text Processing**: dynamicPrompts, editAttention
|
||||
- **Platform Support**: electronAdapter
|
||||
|
||||
1. **Registration-based:** Extensions must register themselves with the application using `app.registerExtension()`
|
||||
2. **Hook-driven:** Extensions interact with the system through predefined hooks
|
||||
3. **Non-intrusive:** Extensions should avoid directly modifying core objects where possible
|
||||
and more.
|
||||
|
||||
## Core Extensions List
|
||||
## See Also
|
||||
|
||||
The following table lists ALL core extensions in the system as of 2025-01-30:
|
||||
|
||||
### Main Extensions
|
||||
|
||||
| Extension | Description | Category |
|
||||
|-----------|-------------|----------|
|
||||
| clipspace.ts | Implements the Clipspace feature for temporary image storage | Image |
|
||||
| contextMenuFilter.ts | Provides context menu filtering capabilities | UI |
|
||||
| dynamicPrompts.ts | Provides dynamic prompt generation capabilities | Prompts |
|
||||
| editAttention.ts | Implements attention editing functionality | Text |
|
||||
| electronAdapter.ts | Adapts functionality for Electron environment | Platform |
|
||||
| groupNode.ts | Implements the group node functionality to organize workflows | Graph |
|
||||
| groupNodeManage.ts | Provides group node management operations | Graph |
|
||||
| groupOptions.ts | Handles group node configuration options | Graph |
|
||||
| index.ts | Main extension registration and coordination | Core |
|
||||
| load3d.ts | Supports 3D model loading and visualization | 3D |
|
||||
| maskEditorOld.ts | Legacy mask editor implementation | Image |
|
||||
| maskeditor.ts | Implements the mask editor for image masking operations | Image |
|
||||
| nodeTemplates.ts | Provides node template functionality | Templates |
|
||||
| noteNode.ts | Adds note nodes for documentation within workflows | Graph |
|
||||
| previewAny.ts | Universal preview functionality for various data types | Preview |
|
||||
| rerouteNode.ts | Implements reroute nodes for cleaner workflow connections | Graph |
|
||||
| saveImageExtraOutput.ts | Handles additional image output saving | Image |
|
||||
| saveMesh.ts | Implements 3D mesh saving functionality | 3D |
|
||||
| simpleTouchSupport.ts | Provides basic touch interaction support | Input |
|
||||
| slotDefaults.ts | Manages default values for node slots | Nodes |
|
||||
| uploadAudio.ts | Handles audio file upload functionality | Audio |
|
||||
| uploadImage.ts | Handles image upload functionality | Image |
|
||||
| webcamCapture.ts | Provides webcam capture capabilities | Media |
|
||||
| widgetInputs.ts | Implements various widget input types | Widgets |
|
||||
|
||||
### load3d Subdirectory
|
||||
Located in `extensions/core/load3d/`:
|
||||
|
||||
| File | Description | Type |
|
||||
|------|-------------|------|
|
||||
| AnimationManager.ts | Manages 3D animations | Manager |
|
||||
| CameraManager.ts | Handles camera controls and positioning | Manager |
|
||||
| ControlsManager.ts | Manages 3D scene controls | Manager |
|
||||
| EventManager.ts | Handles 3D scene events | Manager |
|
||||
| interfaces.ts | TypeScript interfaces for 3D functionality | Types |
|
||||
| LightingManager.ts | Manages scene lighting | Manager |
|
||||
| Load3DConfiguration.ts | Configuration for 3D loading | Config |
|
||||
| Load3d.ts | Core 3D loading functionality | Core |
|
||||
| Load3dAnimation.ts | Animation-specific 3D operations | Animation |
|
||||
| Load3dUtils.ts | Utility functions for 3D operations | Utils |
|
||||
| LoaderManager.ts | Manages various 3D file loaders | Manager |
|
||||
| ModelExporter.ts | Exports 3D models to different formats | Export |
|
||||
| ModelManager.ts | Manages 3D model lifecycle | Manager |
|
||||
| NodeStorage.ts | Handles storage for 3D nodes | Storage |
|
||||
| PreviewManager.ts | Manages 3D model previews | Manager |
|
||||
| RecordingManager.ts | Handles 3D scene recording | Manager |
|
||||
| SceneManager.ts | Core 3D scene management | Manager |
|
||||
| ViewHelperManager.ts | Manages 3D view helpers and gizmos | Manager |
|
||||
|
||||
### Conditional Lines Subdirectory
|
||||
Located in `extensions/core/load3d/conditional-lines/`:
|
||||
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| ColoredShadowMaterial.js | Material for colored shadow rendering |
|
||||
| ConditionalEdgesGeometry.js | Geometry for conditional edge rendering |
|
||||
| ConditionalEdgesShader.js | Shader for conditional edges |
|
||||
| OutsideEdgesGeometry.js | Geometry for outside edge detection |
|
||||
|
||||
### Lines2 Subdirectory
|
||||
Located in `extensions/core/load3d/conditional-lines/Lines2/`:
|
||||
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| ConditionalLineMaterial.js | Material for conditional line rendering |
|
||||
| ConditionalLineSegmentsGeometry.js | Geometry for conditional line segments |
|
||||
|
||||
### ThreeJS Override Subdirectory
|
||||
Located in `extensions/core/load3d/threejsOverride/`:
|
||||
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| OverrideMTLLoader.js | Custom MTL loader with enhanced functionality |
|
||||
|
||||
## Extension Development
|
||||
|
||||
When developing or modifying extensions, follow these best practices:
|
||||
|
||||
1. **Use provided hooks** rather than directly modifying core application objects
|
||||
2. **Maintain compatibility** with other extensions
|
||||
3. **Follow naming conventions** for both extension names and settings
|
||||
4. **Properly document** extension hooks and functionality
|
||||
5. **Test with other extensions** to ensure no conflicts
|
||||
|
||||
### Extension Registration
|
||||
|
||||
Extensions are registered using the `app.registerExtension()` method:
|
||||
|
||||
```javascript
|
||||
app.registerExtension({
|
||||
name: "MyExtension",
|
||||
|
||||
// Hook implementations
|
||||
async init() {
|
||||
// Implementation
|
||||
},
|
||||
|
||||
async beforeRegisterNodeDef(nodeType, nodeData, app) {
|
||||
// Implementation
|
||||
}
|
||||
|
||||
// Other hooks as needed
|
||||
});
|
||||
```
|
||||
|
||||
## Extension Hooks
|
||||
|
||||
ComfyUI extensions can implement various hooks that are called at specific points in the application lifecycle:
|
||||
|
||||
### Hook Execution Sequence
|
||||
|
||||
#### Web Page Load
|
||||
|
||||
```
|
||||
init
|
||||
addCustomNodeDefs
|
||||
getCustomWidgets
|
||||
beforeRegisterNodeDef [repeated multiple times]
|
||||
registerCustomNodes
|
||||
beforeConfigureGraph
|
||||
nodeCreated
|
||||
loadedGraphNode
|
||||
afterConfigureGraph
|
||||
setup
|
||||
```
|
||||
|
||||
#### Loading Workflow
|
||||
|
||||
```
|
||||
beforeConfigureGraph
|
||||
beforeRegisterNodeDef [zero, one, or multiple times]
|
||||
nodeCreated [repeated multiple times]
|
||||
loadedGraphNode [repeated multiple times]
|
||||
afterConfigureGraph
|
||||
```
|
||||
|
||||
#### Adding New Node
|
||||
|
||||
```
|
||||
nodeCreated
|
||||
```
|
||||
|
||||
### Key Hooks
|
||||
|
||||
| Hook | Description |
|
||||
|------|-------------|
|
||||
| `init` | Called after canvas creation but before nodes are added |
|
||||
| `setup` | Called after the application is fully set up and running |
|
||||
| `addCustomNodeDefs` | Called before nodes are registered with the graph |
|
||||
| `getCustomWidgets` | Allows extensions to add custom widgets |
|
||||
| `beforeRegisterNodeDef` | Allows extensions to modify nodes before registration |
|
||||
| `registerCustomNodes` | Allows extensions to register additional nodes |
|
||||
| `loadedGraphNode` | Called when a node is reloaded onto the graph |
|
||||
| `nodeCreated` | Called after a node's constructor |
|
||||
| `beforeConfigureGraph` | Called before a graph is configured |
|
||||
| `afterConfigureGraph` | Called after a graph is configured |
|
||||
| `getSelectionToolboxCommands` | Allows extensions to add commands to the selection toolbox |
|
||||
|
||||
For the complete list of available hooks and detailed descriptions, see the [ComfyExtension interface in comfy.ts](https://github.com/Comfy-Org/ComfyUI_frontend/blob/main/src/types/comfy.ts).
|
||||
|
||||
## Further Reading
|
||||
|
||||
For more detailed information about ComfyUI's extension system, refer to the official documentation:
|
||||
|
||||
- [JavaScript Extension Overview](https://docs.comfy.org/custom-nodes/js/javascript_overview)
|
||||
- [JavaScript Hooks](https://docs.comfy.org/custom-nodes/js/javascript_hooks)
|
||||
- [JavaScript Objects and Hijacking](https://docs.comfy.org/custom-nodes/js/javascript_objects_and_hijacking)
|
||||
- [JavaScript Settings](https://docs.comfy.org/custom-nodes/js/javascript_settings)
|
||||
- [JavaScript Examples](https://docs.comfy.org/custom-nodes/js/javascript_examples)
|
||||
|
||||
Also, check the main [README.md](https://github.com/Comfy-Org/ComfyUI_frontend#developer-apis) section on Developer APIs for the latest information on extension APIs and features.
|
||||
- [Extension Development Guide](/docs/extensions/development.md) - How to develop extensions
|
||||
- [Extension Documentation Index](/docs/extensions/README.md) - Overview of all extension docs
|
||||
- [ComfyExtension Interface](../../types/comfy.ts) - TypeScript interface for extensions
|
||||
Reference in New Issue
Block a user