## ⚙️ Core Systems

### 1. Twitch Account Linking

Players can link their Minecraft account to their Twitch account using a simple in-game command. This is the foundation for tracking watch time and rewards.

- **Command**: `/linktwitch <twitch_username>`

- **Storage**: Linked accounts are stored in `usernames.yml` in the format `twitch_username: minecraft_uuid`.

### 2. Streamer Configuration

Server administrators can easily configure the main Twitch channel to be tracked. The plugin will monitor this channel for live status updates.

- **Configuration**: Set the `twitch_channel` and `twitch_link` in `config.yml`.

- **API Integration**: Requires a Twitch Client ID and Secret to be added to the `config.yml` for Twitch API communication.

### 3. Live Announcements

When the configured streamer goes live, a customizable announcement is broadcast to all players on the server, encouraging them to join the stream.

- **Configuration**: Enable or disable this feature and customize the message in `config.yml`.

- **Example Message**: `§d[Live] %streamer% is now streaming! Watch at: %streamlink%`

### 4. Watch Time Tracking System

The plugin tracks the watch time of all linked players who are online on the Minecraft server while the streamer is live.

- **Logic**: An asynchronous task runs every second to check the streamer's live status and update the watch time for online, linked players.

- **Storage**: Watch time data is stored in `time.yml` for each player, including `seconds_watched` and `unclaimed_rewards`.

### 5. Reward Interval Logic

Rewards are automatically granted to players based on a configurable time interval.

- **Configuration**: Set the `reward_interval` (in seconds), `reward_type` (`points` or `item`), and the `reward` itself in `config.yml`.

- **Example**: If `reward_interval` is 600, a player will receive a reward for every 10 minutes of watch time.

### 6. Offline Reward Handling

If a player earns a reward while they are offline, the plugin stores it as an "unclaimed reward". When the player logs back in, they are notified and given a unique code to redeem their rewards.

- **Logic**: A `PlayerJoinEvent` listener checks for unclaimed rewards and generates a redeem code.

- **Notification**: The player receives a message like: `§eYou’ve earned rewards for watching %streamer%! Use /twitchredeem <code> to claim them.`

### 7. Redeem Code System

A flexible system for redeeming rewards using unique codes. Codes can be generated automatically for offline rewards or manually by streamers/admins.

- **Storage**: Codes are stored in `redeemcodes.yml` with their `reward_type`, `reward`, and `uses_left`.

- **Expiration**: Codes are automatically removed when their `uses_left` reaches 0.

### 8. Streamer Reward Code Generation

Streamers and administrators can generate custom reward codes to share with their audience during a stream.

- **Command**: `/twitchreward generate`

- **Configuration**: The reward type, value, and number of uses for generated codes can be configured in `config.yml`.

### 9. Twitch Points System

An in-plugin currency system that allows players to accumulate "Twitch Points" as rewards.

- **Storage**: Player point balances are stored in `twitchpoints.yml`.

- **Command**: Players can check their balance with `/twitchpoints`.

### 10. Watch Time Tracking (via Twitch IRC)

To provide an accurate watch time tracking system, TwitchRewards999 now integrates directly with Twitch IRC. This system tracks players who are actively participating in the stream's chat.

- **How it works**:

1. The Minecraft plugin connects to the streamer's Twitch chat via Twitch IRC.

2. It tracks users who join or leave the chat, and those who send messages.

3. Only players who are identified as active chatters will have their watch time tracked.

- **Setup**:

1. Configure your Twitch Client ID, Client Secret, and OAuth Token in the plugin's `config.yml`.

## Part 1: Setting up the Twitch Extension (this is a required process)

1. **Create a new Twitch Extension**:

- Go to the [Twitch Developer Console](https://dev.twitch.tv/console).

- Click on "Extensions" in the left-hand menu.

- Click "Create an Extension".

- Give your extension a name (e.g., "MyRewardsExtension") and select "Panel" as the extension type.

- Click "Create Extension".

2. **Get your Extension Credentials**:

- In your extension's dashboard, you will see your **Client ID**.

- Click on the "Settings" tab. Your **Extension Secret** is here.

3. **Generate and Upload the Frontend Files**:

- Start your Minecraft server with the TwitchRewards999 plugin installed. This will automatically generate the `extension_frontend` folder containing `panel.html` and `viewer.js` in the same directory as your plugin's configuration folder (e.g., `plugins/TwitchRewards999/extension_frontend`).

- Go to the "Asset Hosting" tab in your extension's dashboard.

- Drag and drop the contents of the newly generated `extension_frontend` folder (`panel.html` and `viewer.js`) into the upload area.

- Set the "Panel Viewer Path" to `panel.html`.

- Click "Save Changes".

---

## Part 2: Setting up the Minecraft Plugin

1. **Install the Plugin**:

- Place the `TwitchRewards999-1.0.0.jar` file (from the `target` directory) into your Spigot server's `plugins` folder.

- Start your Minecraft server. This will generate the plugin's configuration files.

2. **Configure the Plugin**:

- Open the `plugins/TwitchRewards999/config.yml` file.

- Set the `twitch_channel` to your Twitch username (the channel you want to track).

- Set the `twitch_link` to your Twitch channel URL.

- Fill in your `twitch_client_id` and `twitch_client_secret` (the same ones from your Twitch Extension).

- **Obtain a Twitch OAuth Token:**

- Go to a Twitch Chat OAuth Password Generator (e.g., [https://twitchapps.com/tmi/](https://twitchapps.com/tmi/)).

- Authorize the application to get your OAuth token. It will start with `oauth:`.

- Copy the full token.

- Set the `twitch_oauth_token` in `config.yml` to the OAuth token you just obtained.

- Customize the rest of the settings (rewards, messages, etc.) to your liking.

- Save the `config.yml` file and restart your server or run `/twitchreload`.

---

## Part 3: Final Steps

1. **Activate the Extension**:

- Go back to your Twitch Extension's dashboard.

- Go to the "Version Status" tab and follow the steps to move your extension to "Hosted Test" and then to "Released".

- Once released, you can install the extension on your own channel by going to your Creator Dashboard -> Extensions -> My Extensions.

2. **Test the System**:

- Start streaming on Twitch with the extension active.

- Have a player link their Twitch account in-game with `/linktwitch <their_twitch_username>`.

- Watch the stream for the configured `reward_interval`.

- You should see rewards being granted in-game.

- Check the server console for any errors.

You have now successfully set up the complete TwitchRewards999 system!

---

## 💬 Commands

| Command | Description | Permission |

| ----------------------------- | ------------------------------------------------- | ------------------- |

| `/linktwitch <twitch_user>` | Link your Minecraft account to your Twitch account. | (everyone) |

| `/twitchpoints` | Shows your current Twitch Points balance. | (everyone) |

| `/twitchreward generate` | Generates a reward code for the streamer to share.| `twitchreward.admin`|

| `/twitchredeem <code>` | Redeem a stored or shared reward code. | (everyone) |

| `/twitchreload` | Reloads the plugin's configuration and data. | `twitchreward.admin`|

| `/twitchtime <player>` | See a player's watch time and unclaimed rewards. | `twitchreward.admin`|