# Unity Getting Started

Integrating Twitch into a Unity game with the Twitch plugin

Source: https://dev.twitch.tv/docs/game-engine-plugins/unity-guide/

# Unity Engine

## Initial Settings

Double click the supplied unitypackage (see [Overview](https://dev.twitch.tv/docs/game-engine-plugins.md) for download) and import all files into your project.
Once the import is complete, click the Twitch Menu in the toolbar and then click on edit settings.
The Inspector will then show a Twitch Client ID text box, you must enter a valid Client ID in that box for the plugins to function.
Navigate to the [Developer Console](https://dev.twitch.tv/console/apps) to create a new application or use an existing application's Client ID.

![Unity Plugin Settings image](https://dev.twitch.tv/docs/assets/images/pluginsettingsunity.png)

## Experimental Mac Support

Versions after 121523 have experimental support for Mac-based development environments.
However, the plugins are not signed for Mac. You must run the following command to prevent the OS from blocking the dylib:

```bash
xattr -rd com.apple.quarantine TwitchSDK.unitypackage
```

Alternatively, you can build your own version of the plugin with your own signature via our GitHub source. See [Overview](https://dev.twitch.tv/docs/game-engine-plugins.md) regarding a request for the codebase.

Note that you must use Unity version 2022.3 or greater.

## Authentication

Authentication requires you to maintain two GameTask objects of type AuthenticationInfo and AuthState, `GameTask<AuthenticationInfo>` and `GameTask<AuthState>`.
`GetAuthState()` can be called at any time to ensure that your user's auth state is up to date. Generally, we suggest you do this in the `start` function of your management code.

Prior to first login, you must call `Twitch.API.GetAuthenticationInfo(Scopes)` with one or more valid `TwitchOAuthScope`, this will return an object of type `GameTask<AuthenticationInfo>`.

Once `GetAuthState()` is called at least once, you can check the status of the authentication via the `MaybeResult` of the state. If the `MaybeResult` is not null, you can check its `Status` such as `curAuthState.MaybeResults.Status`.
Possible status states are `AuthStatus.LoggedIn`, `AuthStatus.LoggedOut`, and `AuthStatus.WaitingForCode`.
If the status is `WaitingForCode`, then your user needs to complete the login flow. To do so, create a `UserAuthInfo` object via the `MaybeResult` of `Twitch.API.GetAuthenticationInfo(Scopes)`.
If the `MaybeResult` is not null, then you should be able to launch a browser window with the URI from the `UserAuthInfo` object. 

```cs
Application.OpenURL("{UserAuthInfo.uri}")
```

Note in the example class below, it is expected that you call `GetAuthInformation()` from some external source, such as a login menu.

### List of Scopes

| Scope Name | Type of Access |
| --- | --- |
| `TwitchOAuthScope.Bits.Read.Scope` | View Bits information for a channel. |
| `TwitchOAuthScope.Channel.ManageBroadcast.Scope` | Manage a channel's broadcast configuration, including updating channel configuration and managing stream markers and stream tags. |
| `TwitchOAuthScope.Channel.ManagePolls.Scope` | Manage a channel's polls. |
| `TwitchOAuthScope.Channel.ManagePredictions.Scope` | Manage of channel’s Channel Points Predictions |
| `TwitchOAuthScope.Channel.ManageRedemptions.Scope` | Manage Channel Points custom rewards and their redemptions on a channel. |
| `TwitchOAuthScope.Channel.ReadHypeTrain.Scope` | View Hype Train information for a channel. |
| `TwitchOAuthScope.Clips.Edit.Scope` | Manage Clips for a channel. |
| `TwitchOAuthScope.User.ReadSubscriptions.Scope` | View if an authorized user is subscribed to specific channels. |

Note some of these scopes are required for functionality of a given type. Such as Polls requiring the ManagePolls scope.
Please refer to [Scopes](https://dev.twitch.tv/docs/authentication/scopes.md) to learn more about which scopes you should select.

### Example of an Authentication Manager class

```cs
using TwitchSDK;
using TwitchSDK.interop;
public class AuthManager : MonoBehaviour
{
	GameTask<AuthenticationInfo> AuthInfoTask;
	GameTask<AuthState> curAuthState;
	
	void start()
	{
		updateAuthState();
	}
	
	public void UpdateAuthState()
	{
		curAuthState = Twitch.API.GetAuthState();
		if(curAuthState.MaybeResult.Status == AuthStatus.LoggedIn)
		{
			// user is logged in
		}
		if (curAuthState.MaybeResult.Status == AuthStatus.LoggedOut)
		{
			// user is logged out, do something
			// In this example you could also call GetAuthInformation() to retrigger login
		}
		if (curAuthState.MaybeResult.Status == AuthStatus.WaitingForCode)
		{
			// Waiting for code
			var UserAuthInfo = Twitch.API.GetAuthenticationInfo(RequiredScopes).MaybeResult;
			if(UserAuthInfo == null)
			{
				// User is still loading
			}
			// We have reached the state where we can ask the user to login
			Application.OpenURL("{UserAuthInfo.Uri}{UserAuthInfo.UserCode}");
		}
	}

	// Triggered by something external, like a login button on a options menu screen
	public void GetAuthInformation()
	{
	  // Check to see if the user is currently logged in or not.
		if (AuthInfoTask == null)
		{
			// This example uses all scopes, we suggest you only request the scopes you actively need.
			var scopes = TwitchOAuthScope.Bits.Read.Scope + " " + TwitchOAuthScope.Channel.ManageBroadcast.Scope + " " + TwitchOAuthScope.Channel.ManagePolls.Scope + " " + TwitchOAuthScope.Channel.ManagePredictions.Scope + " " + TwitchOAuthScope.Channel.ManageRedemptions.Scope + " " + TwitchOAuthScope.Channel.ReadHypeTrain.Scope + " " + TwitchOAuthScope.Clips.Edit.Scope + " " + TwitchOAuthScope.User.ReadSubscriptions.Scope;
			TwitchOAuthScope tscopes = new TwitchOAuthScope(scopes);
			AuthInfoTask = Twitch.API.GetAuthenticationInfo(tscopes);
		}
	}
}
```	

## Polls

When utilizing the poll functionality of the plugins, you must maintain a GameTask of type poll, `GameTask<Poll>`.
You can use that task to determine if a poll has started, is active, or has returned results.
To create a new poll, make a new object of type `GameTask<Poll>` then use the new poll function and pass in a `PollDefinition` for example: 

```cs
OurPoll = Twitch.API.NewPoll(new PollDefinition { Title = "some title", Choices = {"a","b","c"}, Duration = someNumber})
```

Once created, you can use the `MaybeResult` to check the results.

```cs
var PollResult = OurPoll?.MaybeResult;
```

The resulting variable contains an `Info` object to check status and choice values, i.e., `PollResult.Info.Status` and `PollResult.Info.Choices`.
More information can be found in the reference.

### Example of a Poll Manager class

```cs
using TwitchSDK;
using TwitchSDK.Interop;
public class TwitchPollManager : MonoBehaviour
{
	GameTask<Poll> ActivePoll = null;
	private bool PollHasEnded = false;
	private void Start()
	{
	}
	
	//Called by some external class
	public void StartPoll(string pollTitle, string[] pollChoices)
	{
		// We already polled something, so we don't do anything.
		if (ActivePoll != null)
			return;
		var authStatus = Twitch.API?.GetAuthState().MaybeResult;
		// Not logged in
		if (authStatus?.Status != AuthStatus.LoggedIn)
			return;
		// If we don't have the "Manage Polls" permission, we also give up.
		if (!authStatus.Scopes.Any(a => a == Twitch.TwitchOAuthScope.Channel.ManagePolls.Scope))
			return;
		ActivePoll = Twitch.API.NewPoll(new PollDefinition
		{
			Title = pollTitle,
			Choices = pollChoices,
			Duration = 20, // in seconds
		});
	}
	private void Update()
	{
		if (PollHasEnded)
			return;
		var poll = ActivePoll?.MaybeResult;
		if (poll == null)
			return;
		// This means we have an active poll, and are waiting for it to finish.
		if (poll.Info.Status == PollStatus.Active)
			return;
		// Now we know the poll is finished in some way.
		PollHasEnded = true;
		// This poll was cancelled by someone, so we don't take the results.
		if (poll.Info.Status != PollStatus.Completed)
			return;
		// Now we can tally results and do something
		var votesForChoice1= poll.Info.Choices.Where(a => a.Title == "Yes").Single();
		var votesForChoice2 = poll.Info.Choices.Where(a => a.Title == "No").Single();

		if(votesForChoice1 > votesForChoice2)
			// Do something
		if(votesForChoice2 > votesForChoice1)
			// Do something else
		else // in case they somehow tie
			// Do something else again
	}
}
```

## Predictions

Predictions function much in the same way as polls, only with a limit of two choices for outcomes.
To interact with predictions, you must maintain a GameTask of type Prediction, `GameTask<Prediction>`.
You can use that task to determine if a prediction has been started, is active, or has returned results.
To create a new prediction, make a new object of type `GameTask<Prediction>` then use the new prediction function and pass in a `PredictionDefinition`. For example:

```cs
OurPrediction = Twitch.API.NewPoll(new PollDefinition { Title = "some prediction", Outcomes = {"a","b"}, Duration = someNumber)
```

Once created, you can use the `MaybeResult` to check the results.

```cs
var PredictionResult = OurPrediction?.MaybeResult;
```

The resulting variable contains a `Info` object, You can use this to check status, outcomes, and the winning outcome, i.e., `PredictionResult.Info.Status`, `PredictionResult.Info.WinningOutcomeId`, `PredictionResult.Info.Outcomes`.

`PredictionResult.Info.Outcomes` is a vector containing information about a given outcome, such as number of users and Channel Points used.
More information can be found in our reference.

### Example of a Predictions Manager class

```cs
using TwitchSDK;
using TwitchSDK.Interop;
public class TwitchPredictionManager : MonoBehaviour
{
	GameTask<Prediction> ActivePrediction = null;
	private bool PredictionHasEnded = false;
	private Prediction LocalPrediction = null;

	public void createPrediction(string predictionTitle, string[] predictionChoices)
	{
		// We already polled something, so we don't do anything.
		if (ActivePrediction != null)
			return;
		var authStatus = Twitch.API?.GetAuthState().MaybeResult;
		// Not Logged in
		if (authStatus?.Status != AuthStatus.LoggedIn)
			return;
		// If we don't have the "Manage Predictions" permission, we also give up.
		if (!authStatus.Scopes.Any(a => a == TwitchOAuthScope.Channel.ManagePredictions.Scope))
			return;
		ActivePrediction = Twitch.API.NewPrediction(new PredictionDefinition
		{
			Title = predictionTitle,
			Outcomes = predictionChoices,
			Duration = 20, // in seconds
		});
		// Sets it back to false incase a previous prediction has already ended
		PredictionHasEnded = false;
	}
	
	// Allows you to end a prediction if run is currently running
	public void EndPrediction()
	{
		if (LocalPrediction == null)
		{
			return;
		}
		
		// The resolve command forces one of the outcomes to be selected
		LocalPrediction.Resolve(LocalPrediction.Info.Outcomes[0]);
		Debug.Log("Prediction ended");
	}

	private void Update()
	{
		if (PredictionHasEnded)
			return;
		var prediction = ActivePrediction?.MaybeResult;
		if (prediction == null)
			return;
		// This means we have an active poll, and are waiting for it to finish.
		LocalPrediction = prediction;
		if (prediction.Info.Status == PollStatus.Active)
			return;
		// Now we know the prediction is finished.
		PredictionHasEnded = true;
		// This prediction was cancelled by someone, so we don't take the results.
		if (prediction.Info.Status != PredictionStatus.Completed)
			return;
		// Now we get the winning outcome
		var winningOutcome = prediction.Info.Outcomes.Where(a => a.Id == prediction.Info.WinningOutcomeId);
		// Do something with that			
	}
}
```

## Channel Point Rewards

Channel Point rewards allow you to create dynamic in-game events based on redemptions made by users on a given stream.
This is the most open-ended of all supported functions and, as such, any functionality implemented will be highly dependent on your game's design.

This requires the user to be logged in and have the appropriate `manage:redemptions` scope.

The example below uses Channel Points to provide a list of colors which could be used in various ways in-game.

### Example of a Channel Points Manager class

```cs
using TwitchSDK;
using TwitchSDK.Interop;
public class TwitchChannelPointManager : MonoBehaviour
{
	public void SetSampleRewards()
	{
		CustomRewardDefinition ColorRed = new CustomRewardDefinition();
		ColorRed.Title = "Red!";
		ColorRed.Cost = 10;
		CustomRewardDefinition ColorBlue = new CustomRewardDefinition();
		ColorBlue.Title = "Blue!";
		ColorBlue.Cost = 25;
		CustomRewardDefinition ColorOctarine = new CustomRewardDefinition();
		ColorOctarine.Title = "Octarine!";
		ColorOctarine.Cost = 750;

		List<CustomRewardDefinition> cDefinitionList = new List<CustomRewardDefinition>();
		cDefinitionList.Add(ColorRed);
		cDefinitionList.Add(ColorBlue);
		cDefinitionList.Add(ColorOctarine);

		Twitch.API.ReplaceCustomRewards(cDefinitionList.ToArray());
	}

	public void ClearRewards()
	{
		CustomRewardDefinition Cleared = new CustomRewardDefinition();
		Cleared.Title = "";
		Cleared.Cost = 0;
		Cleared.IsEnabled = false;
		Twitch.API.ReplaceCustomRewards(Cleared);
	}
}
```

Once you have created custom Channel Point rewards, you must subscribe to the associated event as described under [Subscribe to Events](#subscribe-to-events).

## User Info

To retrieve user information, such as `Displayname`, `Viewcount`, or `UserType`, you must maintain a GameTask of type UserInfo, `GameTask<UserInfo>`.
If you wish to retrieve email information, you must request the appropriate scope at authentication.

### Example

```cs
GameTask<UserInfo> UserInfoTask;
string LoginName;
string BroacasterType;
string DisplayName;
string UserType;
string ViewCount;
	
public void GetUserInformation()
{
    if(UserInfoTask == null)
    {
        UserInfoTask = Twitch.API.GetMyUserInfo();
        if(UserInfoTask?.IsCompleted == true)
        {
            if(UserInfoTask.MaybeResult != null)
            {
                LoginName = "Login Name: " + UserInfoTask.MaybeResult.DisplayName;
                BroacasterType = "Broadcaster Type: " + UserInfoTask.MaybeResult.BroadcasterType;
                DisplayName = "Display Name: " + UserInfoTask.MaybeResult.DisplayName;
                UserType = "User Type: " + UserInfoTask.MaybeResult.UserType;
                ViewCount = "View Count: " + UserInfoTask.MaybeResult.ViewCount;
            }
        }
    }
}
```

## Stream Info

To retrieve stream information, such as `ViewerCount`, `Language`, `GameName`, etc. You must maintain a GameTask of type StreamInfo, `GameTask<StreamInfo>`.

### Example

```cs
GameTask<StreamInfo> StreamInfoTask;
string GameName;
bool isMature;
string Language;
string Title;
long ViewerCount;
	
public void GetStreamInformation()
{
    if(StreamInfoTask == null)
    {
        StreamInfoTask = Twitch.API.GetMyStreamInfo();
        if(StreamInfoTask?.IsCompleted == true)
        {
            if(StreamInfoTask.MaybeResult != null)
            {
                GameName = "Game Name: " + StreamInfoTask.MaybeResult.GameName;
                isMature = StreamInfoTask.MaybeResult.IsMature;
                DisplayName = "Language: " + StreamInfoTask.MaybeResult.Language;
                Title = "Title: " + StreamInfoTask.MaybeResult.Title;
                ViewerCount = StreamInfoTask.MaybeResult.ViewerCount;
            }
        }
    }
}
```

## Subscribe to Events

Events such as new followers, subscribers, raids, Hype Trains, etc use a special type of `GameTask<EventStream<>>`.
EventStreams are special in that they also have multiple types.

When working with Events, you have a choice to either use `WaitForEvent` or `TryGetNextEvent`.
We recommend that you only use one at a time. If you plan on requesting this at regular intervals, such as in Update, we suggest using `TryGetNextEvent`.
If the event has been completed, `TryGetNextEvent` will return the task via the out parameter.

### Channel Point Rewards

```cs
GameTask<EventStream<CustomRewardEvent>> CustomRewardEvents;

private void start()
{
  CustomRewardEvents = Twitch.API.SubscribeToCustomRewardEvents();
}

private void update()
{
  CustomRewardEvent CurRewardEvent; 
  CustomRewardEvents.MaybeResult.TryGetNextEvent(out CurRewardEvent);
  if(CurRewardEvent != null)
  {
    // Do something
    Debug.Log("{CurRewardEvent.RedeemerName} has brought {CurRewardEvent.CustomRewardTitle} for {CurRewardEvent.CustomRewardCost}!");
  }
}
```

### Follows

```cs
GameTask<EventStream<ChannelFollowEvent>> FollowEvents;

private void start()
{
  FollowEvents = Twitch.API.SubscribeToChannelFollowEvents();
}

private void update()
{
  ChannelFollowEvent CurFollowEvent; 
  FollowEvents.MaybeResult.TryGetNextEvent(out CurFollowEvent);
  if(CurFollowEvent != null)
  {
    // Do something
    Debug.Log("{CurFollowEvent.UserDisplayName} is now following!");
  }
}
```

### Subscribers

```cs
GameTask<EventStream<ChannelSubscribeEvent>> ChannelSubscribeEvents;

private void start()
{
  ChannelSubscribeEvents = Twitch.API.SubscribeToChannelSubscribeEvents();
}

private void update()
{
  ChannelSubscribeEvent CurSubscriberEvent; 
  ChannelSubscribeEvents.MaybeResult.TryGetNextEvent(out CurSubscriberEvent);
  if(CurSubscriberEvent != null)
  {
    // Do something
    Debug.Log("{CurSubscriberEvent.UserDisplayName} has Subscribed!");
  }
}
```

### Hype Train

```cs
GameTask<EventStream<HypeTrainEvent>> HypeTrainEvents;

private void start()
{
  HypeTrainEvents = Twitch.API.SubscribeToHypeTrainsEvents();
}

private void update()
{
  HypeTrainEvent CurHypeTrainEvent; 
  HypeTrainEvents.MaybeResult.TryGetNextEvent(out CurHypeTrainEvent);
  if(CurHypeTrainEvent != null)
  {
    // Do something
    Debug.Log("The Hypetrain level is {CurHypeTrainEvent.Level}!");
  }
}
```

### Raids

```cs
GameTask<EventStream<ChannelRaidEvent>> RaidEvents;

private void start()
{
  RaidEvents = Twitch.API.SubscribeToChannelRaidEvent();
}

private void update()
{
  ChannelRaidEvent CurRaidEvent; 
  RaidEvents.MaybeResult.TryGetNextEvent(out CurRaidEvent);
  if(CurRaidEvent != null)
  {
    // Do something
    Debug.Log("{CurRaidEvent.FromBroadcasterName} has raided with {CurRaidEvent.Viewers} people!");
  }
}
```
