TwitchSubCounter v2.0.0

A comprehensive Minecraft plugin that displays your Twitch subscriber count on 7-segment displays using Redstone, with advanced v2.0 enterprise features including database support, milestone rewards, automatic backups, and much more.

🌟 Features

Core Features

🔢 7-Segment Display - Real-time subscriber count display using Redstone
🔐 Secure Token Storage - AES-256 encryption for API credentials
📺 Twitch Integration - Helix API with automatic token refresh
🎮 Multi-Display Support - Up to 10 digits (9,999,999,999 subscribers)
⚡ Real-time Updates - Configurable polling interval

v2.0 Enterprise Features

💾 Database Support - SQLite/MySQL for historical data with full backup/restore
🎯 Milestone System - Automatic rewards at subscriber milestones
💼 Backup System - Automatic backups with compression
🔄 Failover Mode - Continue operation during API outages
🚦 Rate Limiting - Prevent command spam and API abuse
👥 Permission Groups - Advanced permission management
🖥️ Configuration GUI - User-friendly in-game settings
📖 Help System - Interactive documentation
🧪 Developer Mode - Testing and profiling tools
🔐 Config Migration - Automatic upgrade from v1.x

📦 Installation

Requirements

Paper/Spigot 1.20.x - 1.21.x
Java 21 or higher
Twitch Developer Application

Quick Start

Download TwitchSubCounter-2.0.0.jar from Releases
Place in your server's plugins folder
Start server to generate configuration files
Get Twitch API credentials from dev.twitch.tv
Configure using /sub setup or edit plugins/TwitchSubCounter/secrets.yml
Bind display blocks: /sub bind <digit> <x> <y> <z>
Start tracking: /sub start

Twitch API Setup

Go to Twitch Developer Console
Click "Register Your Application"
Fill in:
- Name: TwitchSubCounter
- OAuth Redirect URLs: http://localhost:3000
- Category: Application Integration
Copy your Client ID and Client Secret
Use /sub setup in-game to configure

⚙️ Configuration

Basic Setup

# config.yml
twitch:
  channel: "your_channel_name"
  polling-interval-seconds: 30

display:
  max-digits: 4
  leading-zeros: false
  update-delay-ticks: 2

Database Configuration

database:
  enabled: true
  type: sqlite  # or mysql
  mysql:
    host: localhost
    port: 3306
    database: twitchsubs
    username: root
    password: ""

Security Setup

# Set master password for encryption
export TWITCH_MASTER_PASSWORD="your-secure-password"

# Or in secrets.yml
encryption:
  masterPassword: "your-secure-password"

🎮 Commands

Basic Commands

Command	Description	Permission
`/sub help [topic]`	Show help menu	`subcounter.command.status`
`/sub status`	View current status	`subcounter.command.status`
`/sub gui`	Open configuration GUI	`subcounter.gui.use`
`/sub setup`	Run setup wizard	`subcounter.admin`
`/sub bind <digit> [x] [y] [z]`	Bind display block	`subcounter.command.bind`
`/sub unbind <digit>`	Unbind display block	`subcounter.command.bind`
`/sub test <number>`	Test display	`subcounter.command.test`
`/sub start`	Start auto-updates	`subcounter.command.status`
`/sub stop`	Stop auto-updates	`subcounter.command.status`
`/sub reload`	Reload configuration	`subcounter.command.reload`

Advanced Commands

Command	Description	Permission
`/sub milestone <add\|remove\|list>`	Manage milestones	`subcounter.command.milestone`
`/sub backup <create\|restore\|list>`	Backup operations	`subcounter.command.backup`
`/sub database <status\|stats\|clean>`	Database management	`subcounter.command.database`
`/sub debug <toggle\|overlay\|metrics>`	Debug tools	`subcounter.command.debug`
`/sub perms <list\|add\|remove>`	Permission groups	`subcounter.admin`
`/sub mock <enable\|disable\|set>`	Mock mode for testing	`subcounter.command.mock`

🏆 Milestone System

Configure automatic rewards when reaching subscriber milestones:

milestones:
  100:
    commands:
      - "say We reached 100 subscribers!"
      - "give @a diamond 1"
    particle: FIREWORK
    sound: ENTITY_PLAYER_LEVELUP
    announce: true

  500:
    commands:
      - "say Amazing! 500 subscribers!"
      - "give @a emerald 5"
    particle: EXPLOSION_HUGE
    sound: UI_TOAST_CHALLENGE_COMPLETE
    announce: true

Milestone Commands

# Add milestone
/sub milestone add 1000

# Set milestone rewards
/sub milestone setcmd 1000 "give @a diamond_block 1;say 1000 subs!"

# Set milestone effects
/sub milestone particle 1000 FIREWORK
/sub milestone sound 1000 ENTITY_WITHER_SPAWN

# Trigger milestone manually (testing)
/sub milestone trigger 1000

💾 Backup System

Automatic Backups

backup:
  enabled: true
  interval-hours: 24
  max-backups: 7
  on-shutdown: true

Manual Backup Commands

# Create backup
/sub backup create

# List backups
/sub backup list

# Restore backup
/sub backup restore backup_2024-01-15_12-30-45.zip

# Delete old backup
/sub backup delete backup_2024-01-01_00-00-00.zip

🔒 Building the 7-Segment Display

Materials per digit:

7 Redstone Lamps (segments)
7 Observer Blocks
Redstone Dust
Building blocks

Layout (Each digit):

 AAA
F   B
F   B
 GGG
E   C
E   C
 DDD

Binding Display

Build your 7-segment display
Stand on each Observer block
Use /sub bind <digit> <x> <y> <z>
Test with /sub test 1234

🔐 Security Features

AES-256 Encryption for token storage
Rate Limiting to prevent abuse
Permission Groups for access control
Audit Logging for compliance

🚀 Performance

Optimization Features

Async Processing - Non-blocking API calls
Connection Pooling - HikariCP for databases
Smart Caching - Reduce redundant API calls
Batch Processing - Efficient bulk operations

Recommended Settings

performance:
  async-processing: true
  cache-size: 100
  batch-size: 50

# For large servers
database:
  type: mysql
  connection-pool-size: 10

🤝 Troubleshooting

Common Issues

Problem	Solution
API Connection Failed	1. Check credentials with `/sub testapi` 2. Verify channel name (must be lowercase) 3. Check firewall settings
Display Not Updating	1. Verify bindings: `/sub status` 2. Check chunks loaded: `/sub chunks` 3. Test manually: `/sub test 1234`
Permission Denied	1. Check groups: `/sub perms list` 2. Verify permissions: `/sub help permissions` 3. Check OP status
High Memory Usage	1. Reduce cache size 2. Lower polling interval 3. Clean old data: `/sub database clean 7`
Database Errors	1. Check connection: `/sub database status` 2. Verify credentials 3. Check disk space (SQLite)

Debug Steps

Enable debug mode: /sub debug toggle
Check metrics: /sub debug metrics
View logs: Check plugins/TwitchSubCounter/logs/
Test API: /sub testapi
Check failover: /sub failover status

📋 Permission Nodes

Node	Description	Default
`subcounter.admin`	Full admin access	OP
`subcounter.command.*`	All commands	OP
`subcounter.command.status`	View status	Everyone
`subcounter.command.bind`	Bind displays	OP
`subcounter.gui.use`	Use GUI	OP
`subcounter.gui.admin`	Admin GUI	OP
`subcounter.bypass.ratelimit`	Bypass rate limits	OP

🔄 Migration from v1.x

The plugin automatically migrates your configuration from v1.x to v2.0:

What's Preserved

✅ API credentials (now encrypted)
✅ Display bindings
✅ Channel settings
✅ All existing configurations

What's New

Database support (SQLite default)
Milestone rewards system
Goal tracking with Boss Bar
Automatic backup system
Permission groups
GUI configuration
Rate limiting
Failover mode
Developer tools

📝 Changelog

v2.0.0 (2026-02-18)

Major Release - Enterprise Edition

Added

Database Support (SQLite/MySQL)
Milestone Rewards System
Automatic Backup System
Failover Mode
Rate Limiting
Permission Groups
Configuration GUI
Help System
Developer Mode with Mock Mode
Config Migration System
Secure Token Storage (AES-256)
Block Protection System
Tab Completion for Commands
Interactive Help Topics
Full MySQL Backup/Restore

Changed

Token storage now uses AES-256 encryption
Improved Twitch API integration
Enhanced display system
Reorganized command structure
Expanded configuration format

Security

AES-256 token encryption
Permission-based access control
Rate limiting protection
Audit trail logging

Fixed

Memory leaks in display loops
Chunk loading issues
Token expiration handling
Database connection timeouts
Concurrent modification exceptions
Permission inheritance bugs

v1.2.0 (2025-12-01)

Added mock mode for testing
Keep chunks loaded option
Basic permission nodes
Improved error messages

v1.1.0 (2025-10-15)

Multi-digit display support
Leading zeros configuration
Test command for display

v1.0.0 (2025-09-01)

Initial release
Basic 7-segment display
Twitch API integration

🚧 Known Issues & Future Plans

Known Issues

Hype Train events require EventSub (coming soon)
Discord webhook integration incomplete

Coming in v2.1

Goal Tracking with Boss Bar
Audit Logging System
Hype Train Events Support
Test Data Generator
Twitch EventSub for real-time updates
Multiple channel support
Web dashboard interface
Discord webhook integration
Custom display formats
Follower count display

📝 License

This project is licensed under the MIT License:

MIT License

Copyright (c) 2026 boondocksulfur

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

👏 Credits

Author: boondocksulfur
Version: 2.0.0
Libraries Used:
- Paper API
- Twitch Helix API
- HikariCP (Database pooling)
- Gson (JSON parsing)
- SQLite JDBC
- MySQL Connector

📞 Support

Documentation: Use /sub help in-game
Issues: GitHub Issues
Wiki: GitHub Wiki

Made with ❤️ for the Minecraft & Twitch community

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
src/main		src/main
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
pom.xml		pom.xml

Folders and files

Latest commit

History

Repository files navigation

TwitchSubCounter v2.0.0

🌟 Features

Core Features

v2.0 Enterprise Features

📦 Installation

Requirements

Quick Start

Twitch API Setup

⚙️ Configuration

Basic Setup

Database Configuration

Security Setup

🎮 Commands

Basic Commands

Advanced Commands

🏆 Milestone System

Milestone Commands

💾 Backup System

Automatic Backups

Manual Backup Commands

🔒 Building the 7-Segment Display

Materials per digit:

Layout (Each digit):

Binding Display

🔐 Security Features

🚀 Performance

Optimization Features

Recommended Settings

🤝 Troubleshooting

Common Issues

Debug Steps

📋 Permission Nodes

🔄 Migration from v1.x

What's Preserved

What's New

📝 Changelog

v2.0.0 (2026-02-18)

Added

Changed

Security

Fixed

v1.2.0 (2025-12-01)

v1.1.0 (2025-10-15)

v1.0.0 (2025-09-01)

🚧 Known Issues & Future Plans

Known Issues

Coming in v2.1

📝 License

👏 Credits

📞 Support

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages