TwitchCraft

A Minecraft Paper Plugin that allows Twitch viewers to interact with the streamers world without any additional applications required.

Setup

There are only 3 required configuration variables that need to be set to integrate with Twitch. All 3 can be easily retrieved from a website I made for this plugin: TwitchCraft Website

After logging into Twitch, you will be brought back to my website that tells you what your configuration variables should be. It'll look like this:

Then just copy those codes over to the twitch_craft.yml file in the Plugins resource folder and then Boom!! You're ready to start letting your viewers interact with your Minecraft world!

Additional Global Plugin Configurations (optional)

Configuration	Default Value	Other Example's	Description
default_target	"*"	player1,player1 Crazy_Cranberry	A comma separated list that allows you to specify which players the Actions should target by default. "*" means target all players.
connect_to_twitch	true	true false	Set this to false while testing with the Testing Commands.
send_action_message_by_default	true	true false	Whether or not an Action should send a message by default to the player when triggered. This can be override by the action-specific send_message configuration.
allow_test_commands	false	true false	Whether or not the Testing Commands should be enabled.
channel_follows.allow_repeats	false	true false	Whether or not a viewer unfollowing and refollowing should cause the CHANNEL_FOLLOW trigger to trigger again.
polls.title	Which TwitchCraft Action?		The title of the Twitch Polls that will be running on your stream.
polls.duration_seconds	30		How long the Twitch Polls should last. min: 15 max: 1800
polls.seconds_until_next_poll	120		Interval between polls.
polls.num_choices	3		The number of options to be on the poll. min: 2 max: 5
polls.default_weight	1.0	10.0, 0.5, 4.0	Sometimes you may want certain POLL actions to trigger more or less frequently than others. To handle this scenario, I use a weighting system when randomly deciding which items to put in the poll. If a specific POLL Action does not have a defined weight, then this default_weight is used as its weight. POLL Actions with higher weight's will appear on polls more frequently than POLL Actions with lower weight's.

Actions (optional)

The plugin will come set with the same action configuration that I used in my Stream (notably a small stream). So, if you'd rather not think and just play, you can ignore this section too. However, there are lots of cool possible configurations you can do to set up various different unique actions for your stream.

[Configurations that exist on all actions]

Configuration	Required	Description
type	Yes	The type of action. This is the name in all caps with underscores. Example: BUILD_A_HOUSE
target	No	Comma Separated list of Minecraft User names for this action to target. This overrides the default_target configuration. "*" will target all players.
action_message	No	Use this configuration to override the default message that gets sent to targeted players. You can add color and other variables. Example: "{TRIGGER_CAUSE} has triggered {TRIGGER_TYPE}. Let's {COLOR:AQUA}build{COLOR:WHITE} them a {COLOR:GOLD}house!"
send_message	No	Whether or not this action should send the target players a message when triggered. Defaults to true.
trigger.type	Yes	When you want this action to happen. The valid Trigger Types can be found here. Example: CHANNEL_RESUBSCRIBE
trigger.weight	No	This is only used if trigger.type is POLL. If left blank, then the polls.default_weight configuration will be used. Actions with a higher weight are more likely to appear in a poll; whereas, Actions with a lower weight are less likely to appear in a poll.
trigger.pollMessage	No	This is only used if trigger.type is POLL. This is the message that appears for this action when it is on a poll. If left blank, it'll use a default message that I've provided for each Action. Max length is 25 characters.
trigger.min	No	This is only used if trigger.type is CHANNEL_CHEER or SUB_GIFT. A lower bound on the number of bits/subs that need to be donated to trigger this Action. Defaults to 0.
trigger.max	No	This is only used if trigger.type is CHANNEL_CHEER or SUB_GIFT. An upper bound on the number of bits/subs that need to be donated to trigger this Action. Defaults to Integer Max Value.

Build a House

type: BUILD_A_HOUSE

Constructs a house around the targeted player with a random wood type and random wool color. Also creates a sign out front for whoever triggered this event.

Additional Configuration: None

Example Action Configuration

- type: BUILD_A_HOUSE
  action_message: "{TRIGGER_CAUSE} has triggered {TRIGGER_TYPE}. Let's build them
    a {COLOR:GOLD}house!"
  trigger:
    type: CHANNEL_FOLLOW

Can't Stop Won't Stop

type: CANT_STOP_WONT_STOP

Sets the players velocity to the direction they are looking. Makes it pretty difficult to stop.

Additional Configuration:

Configuration	Required	Description
duration_seconds	Yes	How long this Action should last.

Example Action Configuration

- type: CANT_STOP_WONT_STOP
  trigger:
    type: POLL
    weight: 0.5
    poll_message: Zoom Zoom
  duration_seconds: 60

Chest of Goodies

type: CHEST_OF_GOODIES

Spawn a chest of goodies in front of the player. The contents of the chest are customizable.

Additional Configuration:

Configuration	Required	Description
chest_items	Yes	This is a LIST of items using the other configurations in this table
chest_items[*].name	Yes	The name of the item. Must match an ENUM constant from Material.html.
chest_items[*].chance	Yes	The probability that an item appears in the chest. 1.0 is 100% chance and 0.5 is 50% chance and so on.
chest_items[*].min	Yes	If the item happens to be in the chest (randomly determined from chest_items[*].chance), what is the minimum number of this item that should appear in the chest.
chest_items[*].max	Yes	If the item happens to be in the chest (randomly determined from chest_items[*].chance), what is the maximum number of this item that should appear in the chest.

Example Action Configuration

- type: CHEST_OF_GOODIES
  trigger:
    type: POLL
  chest_items:
    - name: LEATHER_HELMET
      chance: 0.4
      min: 1
      max: 2
    - name: LEATHER
      chance: 0.9
      min: 4
      max: 7
    - name: BREAD
      chance: 0.9
      min: 3
      max: 9

Custom Command

type: CUSTOM_COMMAND

A customizable command. Whatever you type in for the command configuration will be executed on the server. Use {TRIGGER_TYPE}, {QUANTITY}, {PLAYER} and {PLAYER_LOCATION} to interpolate respectively.

Additional Configuration:

Configuration	Required	Description
command	Yes	The command to be executed (Do not include the starting forward slash)

Example Action Configuration

- type: CUSTOM_COMMAND
  trigger:
    type: CHANNEL_RESUBSCRIBE
  command: summon zombie {PLAYER_LOCATION}

Delete A Chunk

type: DELETE_A_CHUNK

Delete a nearby chunk slowly or quickly. (Leaves the bottom row of bedrock)

Additional Configuration:

Configuration	Required	Description
radius	Yes	0 for the chunk the player is in, 1 would create a 3x3 of chunks around the player and pick one at random.
rows_per_tick	Yes	This is a Double. 0.5 would delete 1 row every 2 ticks. 2.0 would delete 2 rows every 1 tick.

Example Action Configuration

- type: DELETE_A_CHUNK
  trigger:
    type: CHANNEL_RESUBSCRIBE
  radius: 0
  rows_per_tick: 0.5

Drop All Items

type: DROP_ALL_ITEMS

Drop all a players items around them, a minor inconvenience that could turn ugly quick given certain environments.

Additional Configuration: None

Example Action Configuration

- type: DROP_ALL_ITEMS
  trigger:
    type: POLL

Entity Spawn

type: ENTITY_SPAWN

Spawn in entities around the player. This could be friendly entities... or 20 withers.

Additional Configuration:

Configuration	Required	Description
entity	Yes	The entity to be spawned in. Must match an ENUM constant from EntityType.html.
quantity	No	How many of this entity to be spawned in around the player.
use_trigger_quantity	No	If true, it will use the number of bits or gifted subs to determine the number of chickens to spawn. If true, quantity_factor must be set. If false or missing, quantity must be set.
quantity_factor	No	What to multiple the number of bits/subs by to determine how many entities to spawn
is_baby	No	Spawn this entity as a baby if possible. Default: false.
radius_from_player	Yes	How far away the entities should spawn from the player. The entities will spawn in a random spot within this radius.

Example Action Configuration

- type: ENTITY_SPAWN
  target: Crazy_Cranberry
  trigger:
    type: POLL
    weight: 0.3
    poll_message: Spawn Zombies!
  entity: ZOMBIE
  quantity: 3
  use_trigger_quantity: false
  radius_from_player: 5
  is_baby: true

or

- type: ENTITY_SPAWN
  target: Crazy_Cranberry
  trigger:
    type: SUB_GIFT
  entity: WITHER
  use_trigger_quantity: true
  quantity_factor: 1.0
  radius_from_player: 50

Explosion

type: EXPLOSION

Detonate an Explosion centered at the players' location. Players are immune to their own explosions.

Additional Configuration:

Configuration	Required	Description
power	Yes	How powerful the explosion should be. For reference, TNT is power 4.

Example Action Configuration

- type: EXPLOSION
  trigger:
    type: SUB_GIFT
    min: 1
    max: 1
  power: 6 

Flying Cow

type: FLYING_COW

Send Flying Exploding Cows at the targeted player! They explode on collision with a block. They can do some serious damage.

Additional Configuration:

Configuration	Required	Description
num_cows	Yes	How many cows to be thrown at the player.
seconds_between_cows	Yes	How long before the next cow is thrown.
distance_from_player	Yes	How far away the cows are from the player when launched.
cow_velocity	Yes	How fast the cow should be traveling. Trajectory is calculated based on this and distance_from_player.

Example Action Configuration

- type: FLYING_COW
  trigger:
    type: POLL
  num_cows: 5
  seconds_between_cows: 5
  distance_from_player: 15
  cow_velocity: 0.9

Give Item

type: GIVE_ITEM

Give the player a certain amount of any item.

Additional Configuration:

Configuration	Required	Description
item	Yes	The item type. Must match an ENUM constant from Material.html.
quantity	Yes	How many of the item should be given to the player.

Example Action Configuration

- type: GIVE_ITEM
  trigger:
    type: POLL
    weight: 0.1
  item: DIAMOND_AXE
  quantity: 1

Mega Jump (Paper only)

type: MEGA_JUMP

Mega Jump.

Additional Configuration:

Configuration	Required	Description
num_jumps	Either num_jumps or duration_seconds must be set	How many jumps are mega.
duration_seconds	Either num_jumps or duration_seconds must be set	How long mega jump lasts.
end_message	No	A message to let the player know the mega jumps are over.

Example Action Configuration

- type: MEGA_JUMP
  trigger:
    type: POLL
  num_jumps: 3
  end_message: "No more mega jumps."

No Jumping (Paper only)

type: NO_JUMPING

(Do you really need a gif of me running around and not jumping?)

Prevents the player from jumping for a set duration.

Additional Configuration:

Configuration	Required	Description
duration_seconds	Yes	How long the player will be unable to jump.
end_message	No	A message to let the player know they can jump again.

Example Action Configuration

- type: NO_JUMPING
  trigger:
    type: POLL
  duration_seconds: 60
  end_message: "Okay you can jump again."

Piñata Chickens

type: PINATA_CHICKENS

Spawn chickens that are one-hittable and drop something random when killed. It could be a trident, or a stick, or even some lava.

Additional Configuration:

Configuration	Required	Description
num_chickens	No	How many Piñata Chickens to spawn
use_trigger_quantity	Yes	If true, it will use the number of bits or gifted subs to determine the number of chickens to spawn. If true, quantity_factor must be set. If false, num_chickens must be set.
quantity_factor	No	What to multiple the number of bits/subs by to determine how many chickens to spawn

Example Action Configuration

- type: PINATA_CHICKENS
  trigger:
    type: CHANNEL_CHEER
  #num_chickens: 5
  use_trigger_quantity: true
  quantity_factor: 0.2

Potion Effect

type: POTION_EFFECT

Apply a potion effect to the player.

Additional Configuration:

Configuration	Required	Description
level	Yes	How strong the potion effect should be.
duration_seconds	Yes	How strong the potion effect should last.
potion_type	Yes	Must match an ENUM constant from PotionEffectType.html. Or use RANDOM, RANDOM_GOOD, or RANDOM_BAD for a random effect.

Example Action Configuration

- type: POTION_EFFECT
  trigger:
    type: POLL
    weight: 0.3
  level: 2
  duration_seconds: 45
  potion_type: RANDOM_GOOD

Raid

type: RAID

Gives the player the Bad Omen effect and then spawns a villager which triggers a raid.

Additional Configuration:

Configuration	Required	Description
bad_omen_level	Yes	The Bad Omen level to give the player before the raid triggers.

Example Action Configuration

- type: RAID
  trigger:
    type: POLL
  bad_omen_level: 2

Random Item Removal

type: RANDOM_ITEM_REMOVAL

Randomly removes items from the players inventory.

Additional Configuration:

Configuration	Required	Description
num_stacks	Yes	The number of item stacks to remove from.
num_per_stack	Yes	The number of items to be removed per stack.

Example Action Configuration

- type: RANDOM_ITEM_REMOVAL
  trigger:
    type: POLL
  num_stacks: 2
  num_per_stack: 1

Rotating Hotbar

type: ROTATING_HOTBAR

Rotate the players hotbar, making it very annoying to do even the simplest tasks.

Additional Configuration:

Configuration	Required	Description
num_rotations	Yes	The number of rotations.
seconds_between_rotations	Yes	How long before rotating.

Example Action Configuration

- type: ROTATING_HOTBAR
  trigger:
    type: POLL
  num_rotations: 10
  seconds_between_rotations: 3

Send to Nether

type: SEND_TO_NETHER

Send the player to the nether's spawn location. A Return portal is spawned in somewhere nearby to take them back to where they were.

Additional Configuration:

Configuration	Required	Description
nether_portal_possible_radius	Yes	The radius of which the return portal can spawn in

Example Action Configuration

- type: SEND_TO_NETHER
  trigger:
    type: POLL
  nether_portal_possible_radius: 25

Soup Man (Paper only)

type: SOUP_MAN

The soup man really wants soup and you better give it to him.

Additional Configuration:

Configuration	Required	Description
minutes_till_angry	Yes	The radius of which the return portal can spawn in.
halfway_message	No	The message to send to the player when half the time has expired.
angry_message	No	The message to send to the player when time has expired and now the soup man will kill the player.
satisfied_message	No	The message to send to the player when they have successfully completed the soup quest.

Example Action Configuration

- type: SOUP_MAN
  trigger:
    type: POLL
  minutes_till_angry: 20

WaterLog

type: WATERLOG

Constantly spawn water wherever the player is standing. Little goofy, little annoying.

Additional Configuration:

Configuration	Required	Description
duration_seconds	Yes	How long the waterlog should last.

Example Action Configuration

- type: WATERLOG
  trigger:
    type: POLL
  duration_seconds: 60

Weeping Angel

type: WEEPING_ANGEL

Weeping Angels are lethal, indestructible and can only move when you aren't looking at them.

Additional Configuration:

Configuration	Required	Description
seconds_till_despawn	Yes	How long until the Weeping Angel crumbles away.
distance_from_player	Yes	How far away the Weeping Angel spawns from the player.
end_message	Yes	The message to send to the player to let them know the Weeping Angel is gone.

Example Action Configuration

- type: WEEPING_ANGEL
  trigger:
    type: POLL
  seconds_till_despawn: 1800
  distance_from_player: 30
  end_message: "The Weeping Angel has withered away."

Commands

• TwitchCraftRefresh: Reloads the twitch_craft.yml configuration so the plugin has the most up-to-date configuration.
• TwitchCraftReconnect: Attempt to reconnect to Twitch. For example, after loading the plugin for the first time, you'll want to update the twitch_craft.yml with your tokens from Setup and then run TwitchCraftRefresh and TwitchCraftReconnect.
• CreatePoll: Create a poll in twitch. This should happen automatically (after initial startup time), but just in case, you can use this command.

Testing Commands

These commands are great for testing out different actions before going live on twitch. You can simulate each Twitch Trigger.

• ChannelCheer {QUANTITY}: Triggers an event as if someone just donated {QUANTITY} bits.
• ChannelFollow: Triggers an event as if someone just followed the channel.
• ChannelResubscribe: Triggers an event as if someone just Resubscribed.
• ChannelSubscribe: Triggers an event as if someone just Subscribed.
• PollEnd {WINNING_RESULT}: Triggers an event as if a Twitch poll just ended and {WINNING_RESULT} was the winning option.
• SubGift {QUANTITY}: Triggers an event as if someone just gifted {QUANTITY} subs.