Skip to content

Commit 9305ad0

Browse files
velascode64velascode64
committed
add readme
1 parent 7a231b0 commit 9305ad0

File tree

2 files changed

+274
-0
lines changed

2 files changed

+274
-0
lines changed

‎README.md‎

Lines changed: 274 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,274 @@
1+
# ElizaOS Registry
2+
3+
<img src="static/img/eliza_banner.jpg" alt="Eliza Banner" width="100%" />
4+
5+
6+
## Intro
7+
Eliza now supports dynamic plugin loading directly from the package registry.
8+
9+
10+
### Available Plugins
11+
12+
All official plugins are hosted at [github.com/elizaos-plugins](https://github.com/elizaos-plugins/). Currently available plugins include:
13+
14+
- [@elizaos/plugin-solana](https://github.com/elizaos-plugins/plugin-solana) - Solana blockchain integration
15+
- [@elizaos/client-discord](https://github.com/elizaos-plugins/client-discord) - Discord bot integration
16+
- [@elizaos/client-twitter](https://github.com/elizaos-plugins/client-twitter) - Twitter bot integration
17+
- [@elizaos/plugin-whatsapp](https://github.com/elizaos-plugins/plugin-whatsapp) - WhatsApp integration
18+
- [@elizaos/plugin-browser](https://github.com/elizaos-plugins/plugin-browser) - Web scraping capabilities
19+
- [@elizaos/plugin-pdf](https://github.com/elizaos-plugins/plugin-pdf) - PDF processing
20+
- [@elizaos/plugin-image](https://github.com/elizaos-plugins/plugin-image) - Image processing and analysis
21+
- [@elizaos/plugin-video](https://github.com/elizaos-plugins/plugin-video) - Video processing capabilities
22+
- [@elizaos/plugin-llama](https://github.com/elizaos-plugins/plugin-llama) - Local LLaMA model integration
23+
24+
Visit the our [Registry Hub](hhttps://eliza-plugins-hub.vercel.app/)
25+
26+
### Adding Plugins on eliza
27+
1. **package.json:**
28+
```json
29+
{
30+
"dependencies": {
31+
"@elizaos/plugin-solana": "github:elizaos-plugins/plugin-solana",
32+
"@elizaos/plugin-twitter": "github:elizaos-plugins/plugin-twitter"
33+
}
34+
}
35+
```
36+
37+
2. **Character configuration:**
38+
```json
39+
{
40+
"name": "MyAgent",
41+
"plugins": [
42+
"@elizaos/plugin-solana",
43+
"@elizaos/plugin-twitter"
44+
]
45+
}
46+
```
47+
48+
## Plugin Architecture
49+
50+
### Plugin Development
51+
52+
Eliza uses a unified plugin architecture where everything is a plugin - including clients, adapters, actions, evaluators, and services. This approach ensures consistent behavior and better extensibility. Here's how the architecture works:
53+
54+
1. **Plugin Types**: Each plugin can provide one or more of the following:
55+
- Clients (e.g., Discord, Twitter, WhatsApp integrations)
56+
- Adapters (e.g., database adapters, caching systems)
57+
- Actions (custom functionality)
58+
- Evaluators (decision-making components)
59+
- Services (background processes)
60+
- Providers (data or functionality providers)
61+
62+
2. **Plugin Interface**: All plugins implement the core Plugin interface:
63+
```typescript
64+
type Plugin = {
65+
name: string;
66+
description: string;
67+
config?: { [key: string]: any };
68+
actions?: Action[];
69+
providers?: Provider[];
70+
evaluators?: Evaluator[];
71+
services?: Service[];
72+
clients?: Client[];
73+
adapters?: Adapter[];
74+
};
75+
```
76+
77+
3. **Independent Repositories**: Each plugin lives in its own repository under the [elizaos-plugins](https://github.com/elizaos-plugins/) organization, allowing:
78+
- Independent versioning and releases
79+
- Focused issue tracking and documentation
80+
- Easier maintenance and contribution
81+
- Separate CI/CD pipelines
82+
83+
4. **Plugin Structure**: Each plugin repository should follow this structure:
84+
```
85+
plugin-name/
86+
├── images/
87+
│ ├── logo.jpg # Plugin branding logo
88+
│ ├── banner.jpg # Plugin banner image
89+
├── src/
90+
│ ├── index.ts # Main plugin entry point
91+
│ ├── actions/ # Plugin-specific actions
92+
│ ├── clients/ # Client implementations
93+
│ ├── adapters/ # Adapter implementations
94+
│ └── types.ts # Type definitions
95+
│ └── environment.ts # runtime.getSetting, zod validation
96+
├── package.json # Plugin dependencies
97+
└── README.md # Plugin documentation
98+
```
99+
100+
5. **Package Configuration**: Your plugin's `package.json` must include an `agentConfig` section:
101+
```json
102+
{
103+
"name": "@elizaos/plugin-example",
104+
"version": "1.0.0",
105+
"agentConfig": {
106+
"pluginType": "elizaos:plugin:1.0.0",
107+
"pluginParameters": {
108+
"API_KEY": {
109+
"type": "string",
110+
"description": "API key for the service"
111+
}
112+
}
113+
}
114+
}
115+
```
116+
117+
6. **Plugin Loading**: Plugins are dynamically loaded at runtime through the `handlePluginImporting` function, which:
118+
- Imports the plugin module
119+
- Reads the plugin configuration
120+
- Validates plugin parameters
121+
- Registers the plugin's components (clients, adapters, actions, etc.)
122+
123+
7. **Client and Adapter Implementation**: When implementing clients or adapters:
124+
```typescript
125+
// Client example
126+
const discordPlugin: Plugin = {
127+
name: "discord",
128+
description: "Discord client plugin",
129+
clients: [DiscordClientInterface]
130+
};
131+
132+
// Adapter example
133+
const postgresPlugin: Plugin = {
134+
name: "postgres",
135+
description: "PostgreSQL database adapter",
136+
adapters: [PostgresDatabaseAdapter]
137+
};
138+
139+
// Adapter example
140+
export const browserPlugin = {
141+
name: "default",
142+
description: "Pdf",
143+
services: [PdfService],
144+
actions: [],
145+
};
146+
```
147+
148+
### Environment Variables and Secrets
149+
150+
Plugins can access environment variables and secrets in two ways:
151+
152+
1. **Character Configuration**: Through `agent.json.secret` or character settings:
153+
```json
154+
{
155+
"name": "MyAgent",
156+
"settings": {
157+
"secrets": {
158+
"PLUGIN_API_KEY": "your-api-key",
159+
"PLUGIN_SECRET": "your-secret"
160+
}
161+
}
162+
}
163+
```
164+
165+
2. **Runtime Access**: Plugins can access their configuration through the runtime:
166+
```typescript
167+
class MyPlugin implements Plugin {
168+
async initialize(runtime: AgentRuntime) {
169+
const apiKey = runtime.getSetting("PLUGIN_API_KEY");
170+
const secret = runtime.getSetting("PLUGIN_SECRET");
171+
}
172+
}
173+
```
174+
175+
The `getSetting` method follows this precedence:
176+
1. Character settings secrets
177+
2. Character settings
178+
3. Global settings
179+
180+
### Plugin Registration
181+
1. Add it to your agent's character configuration:
182+
```json
183+
{
184+
"name": "MyAgent",
185+
"plugins": [
186+
"@elizaos/plugin-example"
187+
]
188+
}
189+
```
190+
191+
2. Include it in your package.json:
192+
```json
193+
{
194+
"dependencies": {
195+
"@elizaos/plugin-example": "github:elizaos-plugins/plugin-example"
196+
}
197+
}
198+
```
199+
200+
### Creating a New Plugin
201+
202+
1. Use the [plugin template](https://github.com/elizaos-plugins/plugin-template) as a starting point
203+
2. Implement the Plugin interface:
204+
```typescript
205+
interface Plugin {
206+
actions?: Action[];
207+
evaluators?: Evaluator[];
208+
services?: Service[];
209+
providers?: Provider[];
210+
initialize?(runtime: AgentRuntime): Promise<void>;
211+
}
212+
```
213+
3. Create a plugin.json file with metadata and configuration schema
214+
4. Document your plugin's functionality and required environment variables
215+
216+
217+
### Plugin Development Guidelines
218+
219+
1. **Minimal Dependencies**: Only include necessary dependencies
220+
2. **Clear Documentation**: Document all required environment variables
221+
3. **Error Handling**: Gracefully handle missing or invalid configuration
222+
4. **Type Safety**: Use TypeScript for better developer experience
223+
5. **Testing**: Include tests for core functionality
224+
225+
Visit the [Plugin Development Guide](https://github.com/elizaos-plugins/plugin-image) for detailed information on creating new plugins.
226+
227+
### Plugin Branding and Images
228+
229+
To maintain a consistent and professional appearance across the ElizaOS ecosystem, we recommend including the following assets in your plugin repository:
230+
231+
1. **Required Images:**
232+
- `logo.png` (400x400px) - Your plugin's square logo
233+
- `banner.png` (1280x640px) - A banner image for your plugin
234+
- `screenshot.png` - At least one screenshot demonstrating your plugin's functionality
235+
236+
2. **Image Location:**
237+
```
238+
plugin-name/
239+
├── assets/
240+
│ ├── logo.png
241+
│ ├── banner.png
242+
│ └── screenshots/
243+
│ ├── screenshot1.png
244+
│ └── screenshot2.png
245+
```
246+
247+
3. **README Integration:**
248+
```markdown
249+
# My Amazing Plugin
250+
251+
<div align="center">
252+
<img src="assets/banner.png" alt="Plugin Banner" width="100%">
253+
</div>
254+
255+
## Screenshots
256+
257+
<div align="center">
258+
<img src="assets/screenshots/screenshot1.png" alt="Feature Demo" width="80%">
259+
</div>
260+
```
261+
262+
4. **Image Guidelines:**
263+
- Use clear, high-resolution images
264+
- Keep file sizes optimized (< 500KB for logos, < 1MB for banners)
265+
- Follow the [ElizaOS Brand Guidelines](https://github.com/elizaos-plugins/guidelines/brand.md)
266+
- Include alt text for accessibility
267+
268+
Example banner and logo placement:
269+
270+
<div align="center">
271+
<img src="https://raw.githubusercontent.com/elizaos-plugins/registry/main/assets/plugin-banner-example.png" alt="Plugin Banner Example" width="100%">
272+
</div>
273+
274+
> 💡 **Pro Tip**: Use the [ElizaOS Plugin Banner Generator](https://github.com/elizaos-plugins/tools/banner-generator) to create beautiful, consistent banners for your plugins.

‎static/img/eliza_banner.jpg‎

193 KB
Loading

0 commit comments

Comments
 (0)