search

kanimaru / twitcher

Full Twitch Library for Godot
MIT License
64 stars 8 forks source link
gdscript godot twitch-api

readme

[Beta] Twitcher

.. is a Godot Library for implementing Twitch functionality in Godot. The main purpose is to use this library for easier overlay development. The library can also be used to support Twitch game integration.

Features

Secondary Features

Most of the features are implemented. Bugs are very likely, cause of the amount of generated code.

Install

Upfront information: You will stumble over a Redirect URL. This URL has to point to your PC / Application that the authorization is redirected after the login. In case you have no clue just use http://localhost:7170 and make sure this is the redirect URL in https://dev.twitch.tv and your settings in Godot at Twitch -> Auth -> redirect_url

  1. Checkout the project into your addon folder or use the AssetLib. Important: The path has to be /addons/Twitcher otherwise the internal paths doesn't work anymore. Tries to make the path relative didn't worked 😒
  2. Then enable the Plugin via Project -> Project Settings -> Plugins
  3. Insert your credentials: Project -> Project Settings -> Twitch -> Auth Insert client credentials, find them at Twitch Dev Console use the guide how-to-create-credentials

    Note: for the goblins the secret is invalidated ;)

  4. Call TwitchService.setup(); at some point in your application when you want to start the Twitch integration. See also the examples

Image Transformer

TwitchImageTransformer Is the default transformer for all projects. It doesn't support animation at all and returns static images instead. Version that always should work.

MagickImageTransformer Cause Godot doesn't support GIF by default the library provides a possibility for exchangeable converter. Not everyone needs the GIF support. At default the library doesn't use GIF's and requests only static Emojis. The Converter that is provided by the Lib requires ImageMagick an external program to convert the GIFs to Images and then gather them to SpriteFrames.

NativeImageTransformer The native image transformer uses a ported version of vbousquet/godot-gif-importer I can't guarantee that I ported it correctly from Godot 3 to 4 nor I can guarantee that the original Implementation was correctly. This is an alterantive that has to be battle tested. But this one doesn't need any external Program to work (or even not) :D. Also have a look at jegor377/godot-gif-lzw that is used for the LZW compression. The readme has good links for checking this implementation. Couple of parts was broken and I added a "fix".

In case you want to use another way to convert the GIFs. You can easily create a class that has to support:

extends RefCounted
class_name MyImageTransformer

## Should the animated or static version requested
func is_supporting_animation() -> bool:
    return true

## path is the location where the GIF file is currently stored
## buffer_in is the data of the GIF that is stored at path location
## output_path is the location where the converted data should be saved (optional)
func convert_image(path: String, buffer_in: PackedByteArray, output_path: String) -> SpriteFrames:
    # Implement your custom logic
    return SpriteFrames.new();

When you implemented your converter, you can configure the Twitch Lib to use it in the Advanced Settings of the project settings set Project Settings -> Twitch -> General -> Images -> Image Transformer to the ClassName it will be load at runtime with load() function.

Animated Emojis (with ImageMagick)

To use animated Emojis you need to install ImageMagick and set the path to the executable in the Advanced Settings of the project settings Project Settings -> Twitch -> General -> Images -> Image Magic. In case of windows when you didn't changed the path settings it is enough to write magick into this field. For all other users you need a full path to the executable (untested assumption in case of error open issue please). Also set the Image Transformer to Magic Image Transformer afterwards all emojis you receive should be animated.

  1. Install ImageMagick
  2. Configure usage Configure GIF Support

FAQ

Why are you using SpriteFrames instead of AnimatedTexture?
Animated Textures are deprecated and I don't want to add deprecated stuff to a brand new lib. Better use a solution that is stable on the long run. Otherwise user of the lib has to change their implementation as soon as Godot decides to drop the support fully.
My chat messages have a short delay why?
There is a buffer in the implementation that send the messages one by one. You can find it in the settings at `Twitch -> Websocket -> Irc -> Send Message Delay`. This setting is to prevent you from accidentally get disconnected by Twitch. Values below ~310 might lead to a disconnect after 100 messages.
Why is the generated folder commited to the repository?
This Library targets beginners and the API won't change much anyway. One step less for beginners of this library.
I changed scopes but my token is still invalid.
The token can't auto refresh after scope changes always. In case it happens it is possible to remove the token manually or wait until the token runs up. You can find the token in `user://auth.conf` it's encrypted. Just delete the file and the application will reauthorize next time.
I want to subscribe to the event when the ads starts
  1. Check the `twitch/auth/scopes/channel` scope called `channel_read_ads`
  2. Fille the information in `twitch/eventsub/channel_ad_break_begin/subscribed`
  3. Then subscribe via TwitchEventListener or directly via TwitchService.
  4. Happy event receiving

See also:

Uses a modified version of MagicDumps but has the same limitations. Changed the library to use SpriteFrames instead of AnimatedTextures

Inspired by: GIFT

Known Bugs

Nice to Have

Need Support Find me on https://www.twitch.tv/kani_dev/