feat(effects): add plugin architecture for visual effects
- Extract effects as fully decoupled plugins in engine/effects/ - Add EffectConfig, EffectContext dataclasses and EffectPlugin protocol - Add EffectRegistry for plugin discovery and management - Add EffectChain for ordered pipeline execution - Move built-in effects to effects_plugins/ directory - Add interactive effects config picker during startup - Add NTFY command handler for /effects commands - Add tests for effects system (24 new tests) - Update AGENTS.md with effects plugin documentation - Add conventional commits section to AGENTS.md chore: add coverage.xml to .gitignore
This commit is contained in:
75
AGENTS.md
75
AGENTS.md
@@ -108,3 +108,78 @@ The project uses pytest with strict marker enforcement. Test configuration is in
|
||||
- **eventbus.py** provides thread-safe event publishing for decoupled communication
|
||||
- **controller.py** coordinates ntfy/mic monitoring
|
||||
- The render pipeline: fetch → render → effects → scroll → terminal output
|
||||
|
||||
## Effects Plugin System
|
||||
|
||||
The effects system is implemented as a plugin architecture in `engine/effects/`.
|
||||
|
||||
### Core Components
|
||||
|
||||
| Module | Purpose |
|
||||
|--------|---------|
|
||||
| `effects/types.py` | `EffectConfig`, `EffectContext` dataclasses and `EffectPlugin` protocol |
|
||||
| `effects/registry.py` | Plugin discovery and management (`EffectRegistry`) |
|
||||
| `effects/chain.py` | Ordered pipeline execution (`EffectChain`) |
|
||||
| `effects_plugins/*.py` | Externalized effect plugins |
|
||||
|
||||
### Creating a New Effect
|
||||
|
||||
Create a file in `effects_plugins/` with a class ending in `Effect`:
|
||||
|
||||
```python
|
||||
from engine.effects.types import EffectConfig, EffectContext
|
||||
|
||||
class MyEffect:
|
||||
name = "myeffect"
|
||||
config = EffectConfig(enabled=True, intensity=1.0)
|
||||
|
||||
def process(self, buf: list[str], ctx: EffectContext) -> list[str]:
|
||||
# Process buffer and return modified buffer
|
||||
return buf
|
||||
|
||||
def configure(self, config: EffectConfig) -> None:
|
||||
self.config = config
|
||||
```
|
||||
|
||||
### NTFY Commands
|
||||
|
||||
Send messages to the ntfy topic to control effects:
|
||||
|
||||
```
|
||||
/effects list
|
||||
/effects noise on
|
||||
/effects noise off
|
||||
/effects noise intensity 0.5
|
||||
/effects reorder noise,glitch,fade,firehose
|
||||
```
|
||||
|
||||
## Conventional Commits
|
||||
|
||||
Commit messages follow the [Conventional Commits](https://www.conventionalcommits.org/) specification:
|
||||
|
||||
```
|
||||
<type>(<scope>): <description>
|
||||
|
||||
[optional body]
|
||||
|
||||
[optional footer(s)]
|
||||
```
|
||||
|
||||
### Types
|
||||
|
||||
- `feat`: A new feature
|
||||
- `fix`: A bug fix
|
||||
- `docs`: Documentation only changes
|
||||
- `style`: Changes that don't affect code meaning (formatting)
|
||||
- `refactor`: Code change that neither fixes a bug nor adds a feature
|
||||
- `test`: Adding or updating tests
|
||||
- `chore`: Changes to build process, dependencies, etc.
|
||||
|
||||
### Examples
|
||||
|
||||
```
|
||||
feat(effects): add plugin architecture for visual effects
|
||||
fix(layers): resolve glitch effect not applying on empty buffer
|
||||
docs(AGENTS.md): add effects plugin system documentation
|
||||
test(effects): add tests for EffectChain pipeline ordering
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user