Introduction

[!CAUTION] Note on the currency and accuracy of this documentation

I strive to keep this developer documentation as up to date as possible. Since I am simultaneously working on the actual project and maintaining the documentation on my own, it is not always possible to reflect every change immediately.

Please note the following:

Marking of outdated chapters: Chapters that are out of date will be marked where possible. However, even unmarked sections may no longer reflect the current state of the code.

Use of AI: Some text passages were created with the help of AI. I review them, but cannot guarantee that they are free of errors.

General errors such as typos, inaccurate descriptions, or outdated code examples can occur – even in manually written and unmarked sections.

Your help counts! If you notice incorrect or outdated chapters, feel free to report them via a GitHub Issue – this helps improve the documentation for everyone.

Treat this documentation as a helpful guide, but when documentation and source code contradict each other, the source code is always right.

Welcome to the developer documentation for the Streaming Tool – a project that connects TikTok events with Minecraft.

This documentation is aimed at developers who want to understand:

How the system works internally
How data flows (TikTok → Processing → Minecraft)
How to extend the project (write your own plugins, customize features)

Where to Start?

Profile	Recommended starting point
Basic Python knowledge	Start with Basic Concepts, then Setup
Advanced Python knowledge	System Overview → Python in this project
Extend & customize with Python	Go directly to Plugin Development or Custom $ Commands
Debugging / Troubleshooting	Debugging & Troubleshooting

[!NOTE] If you have knowledge in programming languages other than Python, you can go directly to Create a Plugin without Python. However, you should still look at some chapters to better understand how the system works. This will help you even if you don't know Python. I also recommend looking at Create your own Plugin – even though it is primarily written for Python, there is important information there.

Scope & Focus

The project comprises roughly 3,000–4,000 lines of Python code. We don't analyze every single line – that would be pointless.

Instead, we focus on:

Core architectural components – How is the system structured?
Data flows – How does data move through the system?
Patterns & best practices – What should you pay attention to?
Practical application – How do I write my own plugin?

In the code itself, you will find additional comments that serve as signposts for specific details.

Prerequisites

[!NOTE] This documentation explains how the Streaming Tool system works – but not Python basics themselves.

You need the following prior knowledge:

Basic Python programming concepts (functions, classes, loops)

Command line / terminal navigation

File system fundamentals

If these concepts are new to you: Complete a beginner Python course first, e.g. Python.org Tutorial or Codecademy Python Course. Since we assume these basics here, we save space for depth rather than repetition.

Additionally, you need:

Python 3.12+
Git (for cloning the repository)
An editor or IDE (VS Code, PyCharm, etc.)

Everything required for setup is explained step by step in Setting Up Local Development.

Structure of the Documentation

00 FUNDAMENTALS
  ├─ Fundamentals & Concepts (What is this system?)
  └─ Local Development Setup (How do I set this up?)

01 SYSTEM OVERVIEW
  ├─ How the system works together
  ├─ Receiving data from TikTok
  ├─ Processing data
  └─ Sending data to Minecraft

02 PYTHON & EVENTS (Core logic)
  ├─ Python in this project
  ├─ The main.py file
  ├─ TikTok Client & Event Handler
  │  └─ Gift Events, Follow Events, Like Events
  └─ Threading & Queues

03 MINECRAFT INTEGRATION
  ├─ From event to command
  ├─ The actions.mca file
  ├─ Mapping logic
  └─ mcfunction files

04 SYSTEM ARCHITECTURE
  ├─ Modular structure
  ├─ Control Methods (DCS vs. ICS)
  ├─ PLUGIN_REGISTRY
  └─ Integration with streaming software

05 PLUGIN DEVELOPMENT
  ├─ Plugin structure & setup
  ├─ Events & Webhooks
  ├─ Config & data storage
  ├─ GUI with pywebview
  ├─ Inter-plugin communication
  └─ Error handling & best practices

06 ADVANCED
  └─ Debugging & Troubleshooting

APPENDIX
  ├─ Project structure
  ├─ Config details
  ├─ Update process
  └─ Glossary (terms explained)

The documentation is progressively built: Each chapter builds on the previous ones. But you can always jump to topics that interest you.

The appendix

In addition to the main chapters, there is an Appendix. The appendix contains:

Project structure: Files & folders in detail
Config details: Understanding & extending the configuration file
Update process: How updates work (for maintainers)
Glossary: All technical terms explained

The appendix is a reference – you don't have to read it linearly.

How to best use this documentation

Find your level: Beginner? Then start with Basic Concepts & Terms.
Read progressively: Chapters build on each other.
Don't skip too quickly: If something is unclear, go back to previous chapters.
Use the glossary: Unfamiliar terms? Check the Glossary.
Experiment: Reading is important, but writing code yourself is crucial.

Code examples in this documentation

Where we show code examples, we use this formatting:

# Example Python code
from TikTokLive import TikTokLiveClient

client = TikTokLiveClient(unique_id="my_account")

Info blocks:

[!TIP] Practical recommendation, trick, or best practice to make your work easier or better.

[!NOTE] Supplementary information or background knowledge. Not critical, but often helpful for a better understanding.

[!IMPORTANT] Mandatory information or hard prerequisite. Must be followed for things to work. Not optional.

[!WARNING] Pay close attention here! May lead to errors, problems, or unexpected behavior, but nothing is permanently damaged.

[!CAUTION] Critical notice! Incorrect use can lead to data loss, system errors, or irreversible damage.

Found an error? Questions?

This documentation is constantly being improved. If you:

Find errors → Open a GitHub Issue
Something is unclear → Ask an AI or other developers
Have ideas → Provide feedback in the repository

Good luck!

You are ready. Let's start:

→ Basic Concepts & Terms

→ Setting Up Local Development

Streaming Tool Dev