{"id":43758070,"url":"https://github.com/ez-plugins/ezbanners","last_synced_at":"2026-02-05T15:00:15.768Z","repository":{"id":331977822,"uuid":"1126012228","full_name":"ez-plugins/EzBanners","owner":"ez-plugins","description":"Minecraft plugin to sync plugin and server data to generate banners with up-to-date data","archived":false,"fork":false,"pushed_at":"2026-02-04T16:14:28.000Z","size":42,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-05T03:25:53.188Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ez-plugins.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-31T21:43:24.000Z","updated_at":"2025-12-31T22:14:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ez-plugins/EzBanners","commit_stats":null,"previous_names":["ez-plugins/ezbanners"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ez-plugins/EzBanners","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ez-plugins%2FEzBanners","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ez-plugins%2FEzBanners/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ez-plugins%2FEzBanners/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ez-plugins%2FEzBanners/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ez-plugins","download_url":"https://codeload.github.com/ez-plugins/EzBanners/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ez-plugins%2FEzBanners/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29124793,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-05T14:05:12.718Z","status":"ssl_error","status_checked_at":"2026-02-05T14:03:53.078Z","response_time":65,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-05T15:00:14.769Z","updated_at":"2026-02-05T15:00:15.762Z","avatar_url":"https://github.com/ez-plugins.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# EzBanners\n\nEzBanners collects live server data and securely syncs it to your banner API for dynamic image generation.\n\n**Official Repository:** [github.com/ez-plugins/EzBanners](https://github.com/ez-plugins/EzBanners)\n\n## Artifacts\n\nThis project produces two JAR files:\n\n1. **EzBanners.jar** - The full plugin JAR for Minecraft servers\n   - Contains all plugin classes and resources\n   - Deploy this to your server's `plugins/` folder\n\n2. **EzBanners-api.jar** - The API-only JAR for plugin developers\n   - Contains only the public API interfaces and domain models\n   - Use as a Maven/Gradle dependency when developing plugins that integrate with EzBanners\n   - Available from GitHub Packages: `com.github.ez-plugins:ezbanners:0.3.0`\n\n## Features\n- Compatible with Minecraft 1.7 – 1.21+ (Bukkit/Spigot/Paper)\n- Async HTTP sync with exponential backoff and jitter\n- Optional PlaceholderAPI support\n- Secure token + HMAC signatures\n- Public API for external plugins\n- Configurable feature flags\n\n## Architecture\n\n### Module Structure\n\n#### Domain Layer (`domain/`)\n- **ServerData**: Immutable model for collected server metrics\n- **SyncPayload**: Immutable model for sync payloads with headers\n\n#### Service Layer (`sync/`, `metrics/`, `http/`)\n- **SyncScheduler**: Handles timing and exponential backoff with jitter\n- **SyncExecutor**: Builds payloads and executes HTTP requests\n- **SyncService**: Coordinates scheduling and execution\n- **ServerDataCollector**: Collects server metrics based on config\n- **ApiClient**: Standardized HTTP client with consistent headers\n\n#### Plugin Layer (`lifecycle/`, `command/`)\n- **PluginLifecycle**: Manages startup/shutdown flows\n- **EzBannersPlugin**: Bukkit plugin entry point\n- **Commands**: LinkCommand, ReloadCommand, StatusCommand\n\n#### Configuration (`config/`)\n- **EzBannersConfig**: Type-safe config wrapper with validation\n- **ConfigKeys**: Centralized config key constants\n\n#### Public API (`api/provider/`)\n- **DataProvider**: Interface for custom data providers\n- **PlaceholderProvider**: Interface for custom placeholder providers\n- **EzBannersApi**: Public API for external plugin integration\n\n## Setup\n1. Drop `EzBanners.jar` into your server `plugins/` folder.\n2. Start the server to generate `plugins/EzBanners/config.yml`.\n3. Edit `config.yml` and set:\n   - `api.endpoint`\n   - `api.token` (or use `/ezbanners link \u003ctoken\u003e`)\n4. (Optional) Configure `placeholderapi.mappings` if you use PlaceholderAPI.\n5. Restart or reload the plugin.\n\n## Commands\n- `/ezbanners link \u003ctoken\u003e` — Links the server to your API token\n- `/ezbanners reload` — Reloads the configuration\n- `/ezbanners status` — Shows detailed plugin status\n\n## Permissions\n- `ezbanners.link` — Allows the link command (default: op)\n- `ezbanners.reload` — Allows the reload command (default: op)\n- `ezbanners.status` — Allows the status command (default: op)\n\n## Configuration Reference\n\n### API Configuration\n```yaml\napi:\n  endpoint: \"https://ezbanners.org/api/server/update\"  # Banner API endpoint\n  token: \"\"  # Your API token (use /ezbanners link \u003ctoken\u003e)\n```\n\n### Plugin Stats Configuration\n```yaml\nplugin:\n  endpoint: \"https://ezbanners.org/api/plugins/{plugin_uuid}/data\"\n  uuid: \"\"  # Plugin UUID for stats tracking\n  token: \"\"  # Plugin token for authentication\n```\n\n### Server Configuration\n```yaml\nserver:\n  uuid: \"\"  # Auto-generated server UUID (do not modify)\n```\n\n### Sync Configuration\n```yaml\nsync:\n  interval: 300  # Sync interval in seconds (min: 5)\n  max-backoff: 1200  # Maximum backoff on failure in seconds\n```\n\n### Feature Flags\n```yaml\nfeatures:\n  metrics:\n    enabled: true  # Enable/disable metrics collection\n  placeholders:\n    enabled: true  # Enable/disable PlaceholderAPI integration\n  website-sync:\n    enabled: true  # Enable/disable website sync\n```\n\n### Data Fields\nConfigure which data fields to collect and send:\n```yaml\nenabled:\n  data:\n    fields:\n      - server_name\n      - online_players\n      - max_players\n      - server_version\n      - tps_1m\n      - tps_5m\n      - tps_15m\n      - uptime\n      - motd\n      - whitelist\n      - placeholders\n```\n\n### PlaceholderAPI Mappings\nDefine custom placeholder mappings:\n```yaml\nplaceholderapi:\n  mappings:\n    example_rank: \"%vault_rank%\"\n    example_balance: \"%vault_eco_balance_formatted%\"\n```\n\n### Debug Mode\n```yaml\ndebug:\n  enabled: false  # Enable verbose debug logging\n```\n\n## Public API Usage\n\n### Adding the API Dependency\n\nThe EzBanners API is available as a separate artifact on GitHub Packages from the [ez-plugins/EzBanners](https://github.com/ez-plugins/EzBanners) repository.\n\n#### Maven\nAdd the GitHub Packages repository and dependency to your `pom.xml`:\n\n```xml\n\u003crepositories\u003e\n    \u003crepository\u003e\n        \u003cid\u003egithub\u003c/id\u003e\n        \u003curl\u003ehttps://maven.pkg.github.com/ez-plugins/EzBanners\u003c/url\u003e\n    \u003c/repository\u003e\n\u003c/repositories\u003e\n\n\u003cdependencies\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003ecom.github.ez-plugins\u003c/groupId\u003e\n        \u003cartifactId\u003eezbanners\u003c/artifactId\u003e\n        \u003cversion\u003e0.3.0\u003c/version\u003e\n    \u003c/dependency\u003e\n\u003c/dependencies\u003e\n```\n\n#### Gradle\n```groovy\nrepositories {\n    maven {\n        url = uri(\"https://maven.pkg.github.com/ez-plugins/EzBanners\")\n    }\n}\n\ndependencies {\n    compileOnly 'com.github.ez-plugins:ezbanners:0.3.0'\n}\n```\n\n### For Plugin Developers\n\n#### Implementing a Custom Data Provider\n\n```java\nimport com.skyblockexp.ezbanners.api.provider.DataProvider;\nimport com.skyblockexp.ezbanners.domain.ServerData;\n\npublic class MyDataProvider implements DataProvider {\n    @Override\n    public ServerData collectData() {\n        Map\u003cString, Object\u003e data = new HashMap\u003c\u003e();\n        data.put(\"custom_metric\", getMyMetric());\n        return new ServerData(data);\n    }\n    \n    @Override\n    public String getName() {\n        return \"MyPlugin\";\n    }\n    \n    @Override\n    public int getPriority() {\n        return 10; // Higher = called earlier\n    }\n}\n```\n\n#### Sending Plugin Stats\n\n```java\nimport com.skyblockexp.ezbanners.EzBannersPlugin;\nimport com.skyblockexp.ezbanners.api.EzBannersApi;\n\n// Get API instance\nEzBannersApi api = EzBannersPlugin.getInstance().getApi();\n\n// Send stats once\napi.sendPluginStats(\n    \"your-plugin-uuid\",\n    yourPluginInstance,\n    1,  // server count\n    Bukkit.getOnlinePlayers().size()  // player count\n);\n\n// Or start auto-stats push (every 5 minutes)\napi.startAutoStatsPush(\"your-plugin-uuid\", yourPluginInstance, 300);\n```\n\n## Sync Payload Structure\n\nEach sync sends:\n- **Token**: API authentication token\n- **Server UUID**: Unique server identifier\n- **Timestamp**: Current timestamp in milliseconds\n- **HMAC Signature**: SHA256 signature of request body\n- **Data Fields**: Configured data fields from `enabled.data.fields`\n\n## Backoff Strategy\n\nEzBanners uses exponential backoff with jitter for failed sync attempts:\n- Formula: `interval * 2^failureCount`\n- Jitter: Random 0-25% of calculated backoff\n- Maximum: Capped at `sync.max-backoff` seconds\n- Reset: Failure count resets to 0 on successful sync\n\n## Notes\n- TPS and PlaceholderAPI values are only sent when available\n- HTTP requests are async and never block the main thread\n- All domain models are immutable for thread safety\n- Configuration is validated on load with warnings for missing values\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fez-plugins%2Fezbanners","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fez-plugins%2Fezbanners","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fez-plugins%2Fezbanners/lists"}