Add README

2025-12-26 10:21:06 -08:00
parent 236e6cbcdc
commit b976aae0d8
2 changed files with 79 additions and 58 deletions
@@ -1,6 +1,6 @@
 # Byte-compiled / optimized / DLL files
 __pycache__/
-*.py[codz]
+*.py[cod]
 *$py.class

 # C extensions
@@ -46,7 +46,7 @@ htmlcov/
 nosetests.xml
 coverage.xml
 *.cover
-*.py.cover
+*.py,cover
 .hypothesis/
 .pytest_cache/
 cover/
@@ -94,37 +94,14 @@ ipython_config.py
 #   install all needed dependencies.
 #Pipfile.lock

-# UV
-#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
-#   This is especially recommended for binary packages to ensure reproducibility, and is more
-#   commonly ignored for libraries.
-#uv.lock
-
 # poetry
 #   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
 #   This is especially recommended for binary packages to ensure reproducibility, and is more
 #   commonly ignored for libraries.
 #   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
 #poetry.lock
-#poetry.toml

-# pdm
-#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
-#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
-#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
-#pdm.lock
-#pdm.toml
-.pdm-python
-.pdm-build/
-
-# pixi
-#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
-#pixi.lock
-#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
-#   in the .venv directory. It is recommended not to include this directory in version control.
-.pixi
-
-# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
 __pypackages__/

 # Celery stuff
@@ -136,7 +113,6 @@ celerybeat.pid

 # Environments
 .env
-.envrc
 .venv
 env/
 venv/
@@ -169,39 +145,13 @@ dmypy.json
 cython_debug/

 # PyCharm
-#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  JetBrains specific template is maintainted in a separate JetBrains.gitignore that can
 #  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
+*.pyc

-# Abstra
-# Abstra is an AI-powered process automation framework.
-# Ignore directories containing user credentials, local state, and settings.
-# Learn more at https://abstra.io/docs
-.abstra/
-
-# Visual Studio Code
-#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
-#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
-#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
-#  you could uncomment the following to ignore the entire vscode folder
-# .vscode/
-
-# Ruff stuff:
-.ruff_cache/
-
-# PyPI configuration file
-.pypirc
-
-# Cursor
-#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
-#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
-#  refer to https://docs.cursor.com/context/ignore-files
-.cursorignore
-.cursorindexingignore
-
-# Marimo
-marimo/_static/
-marimo/_lsp/
-__marimo__/
+# Ignore Windows ADS quarantine metadata files
+*:Zone.Identifier
+*:zone.identifier
@@ -0,0 +1,71 @@
+
+# ComfyUI Game Boy Player
+
+Embeds a self-contained Game Boy Advance emulator UI inside a ComfyUI node.
+
+This project vendors a static build of the web emulator UI based on [gba.js.org](https://gba.js.org), so it can run offline inside ComfyUI.
+
+## Install
+
+- **Option A (git clone)**
+  - Clone this repo into:
+    - `ComfyUI/custom_nodes/ComfyUI_GB_Player`
+
+- **Option B (Manager)**
+  - Open Manager and install **ComfyUI_GB_Player**
+
+- **Option C (zip)**
+  - Download the repo as a zip.
+  - Extract it to:
+    - `ComfyUI/custom_nodes/ComfyUI_GB_Player`
+
+Restart ComfyUI after installing.
+
+## Usage
+
+- **Add the node**
+  - In ComfyUI, add the node:
+    - `ComfyGameBoyPlayer`
+
+- **Load a ROM**
+  - The emulator UI is inside the node.
+  - Use the emulator's menu to load a GBA bios, and `.gba` or `.gbc` ROM.
+
+## Notes
+
+- **UI-only node**
+  - This node is a UI/embed node. It does not currently produce ComfyUI image outputs.
+
+- **Offline / vendored web assets**
+  - The emulator assets are shipped in this repo under:
+    - `web/gba/`
+  - To prevent ComfyUI from auto-loading vendored third-party JavaScript as extensions, vendored `.js` files are renamed to:
+    - `.js.txt`
+
+- **ComfyUI theme integration**
+  - The ComfyUI web extension posts theme tokens to the iframe, and the embedded player applies them via CSS variables.
+  - Message types used:
+    - `was-gba-theme`
+    - `was-gba-request-theme`
+
+## Troubleshooting
+
+- **The player UI doesn’t update after changes**
+  - Do a hard refresh in your browser:
+    - `Ctrl+F5`
+  - Or clear browser cache for the ComfyUI site.
+
+- **Node appears but iframe is missing/blank**
+  - Open DevTools Console and look for errors.
+  - Confirm the iframe path resolves:
+    - `extensions/ComfyUI_GB_Player/gba/player/index.html`
+
+- **Iframe seems misaligned during zoom/pan**
+  - Make sure you’re running the latest `web/comfy_gameboy_player.js` from this repo.
+  - If you have multiple copies installed, remove old versions from other `custom_nodes` folders.
+
+## Credits / License
+
+- Emulator UI: GBA Online (`gba.js.org`) (vendored static build)
+- Emulator core: IodineGBA (vendored; see `web/gba/iodineGBA/`)
+- This repository includes third-party components under their respective licenses (see files under `web/gba/`).