Factorio.com | Forums | Wiki | Mod Portal | API Docs
Log in

Twitch Chat Bridge

⚠️ REQUIRES external Python bridge – DOES NOT WORK ALONE! This mod contains the in‑game remote interface and a single installer file (install_bridge.lua). Rename it to .py, place it in your Factorio server root, and run it with Python. The installer will set up the entire Twitch Chat Bridge automatically. Full instructions in the mod description.

Tweaks
2 hours ago
2.0
3
Download

FAQ

Twitch Chat Bridge Mod – Frequently Asked Questions (FAQ)

1. What does this mod actually do?

This mod is one half of a two‑part system. It provides a remote interface inside Factorio that an external Python script (the “Twitch Chat Bridge”) can call to display messages in the game.
Without the external bridge, the mod does nothing. It will not connect to Twitch, it will not show chat, and it will not affect your game in any visible way.

2. Why is the mod useless by itself? Why not bundle the whole bridge?

The Factorio mod portal has strict rules – it forbids uploading executable files such as .py, .exe, .ps1, .sh, .bat, etc. The bridge is written in Python and therefore cannot be placed inside the mod as a normal .py file.
To work around this, we renamed the bridge installer from install_bridge.py to install_bridge.lua. Factorio sees a harmless .lua file and allows it. You, the user, must rename it back to .py after extracting it from the mod.

3. How do I install the full bridge? (Step‑by‑step)

  1. Subscribe to the mod in the Factorio mod portal, or download the .zip manually.
  2. Find the mod folder. On Windows it is usually in %appdata%\Factorio\mods\TwitchChatBridge_1.0.x. Inside that folder you will see control.lua and install_bridge.lua.
  3. Copy install_bridge.lua to your Factorio server root (the folder where your server’s factorio.exe or factorio binary lives).
    Do not copy anything else from the mod folder – only that one file.
  4. Rename install_bridge.lua → install_bridge.py.
    You can do it manually, or in PowerShell:
    powershell Rename-Item install_bridge.lua install_bridge.py
  5. Run the installer:
    bash python install_bridge.py
    If Python is not on your PATH, use the full path (e.g., python3 install_bridge.py).
  6. The installer will create a twitch_chat_bridge/ folder next to your server, along with a README.md, a launcher (Start-FactorioServer.ps1), and a default configuration file.
  7. Edit the config – open twitch_chat_bridge/twitch_chat.config and fill in your Twitch bot credentials and RCON details.
  8. (Optional but recommended) Generate a persistent token:
    bash cd twitch_chat_bridge python twitch_token_helper.py
    Follow the prompts to get a token that never expires.
  9. Start your server using the generated launcher (Windows) or manually:
    powershell .\Start-FactorioServer.ps1
    For Linux / manual start:
    bash cd twitch_chat_bridge python run.py

After the first successful connection, the bridge will save the token and refresh it automatically.

4. I only have the install_bridge.lua file. Where are the other Python files?

They are packed inside the installer script. When you run install_bridge.py, it decodes all the other files from base64 data and writes them to disk. You never need to download or extract any other .py file manually.
The one installer file is all you need.

5. Do I need to rename the whole twitch_chat_bridge folder inside the mod?

No. The mod folder contains a full copy of the bridge for development purposes, but the actual installer that users use is the single install_bridge.lua. You only need that one file. Rename it, run it, and everything is generated for you.

6. Why does the installer need Python? Can’t it be a standalone executable?

The bridge is a Python script that uses several libraries (factorio_rcon, irc, requests). Bundling a standalone executable would be huge and would still trigger the mod portal’s executable filter. By providing a Python script, the user can simply run it with their existing Python installation. The installer will automatically install any missing Python packages (with --user).

7. What Python version do I need? What about Windows vs Linux?

  • Python 3.8 or newer is required (Python 3.7 may work but is untested).
  • The bridge is cross‑platform – it works on Windows, Linux, and macOS.
  • The provided launcher Start-FactorioServer.ps1 is Windows‑only (PowerShell). On Linux you start the bridge manually with python run.py.

8. What are all these files created by the installer?

After running the installer, your server root will contain:

your-server-root/
├── Start-FactorioServer.ps1      (PowerShell launcher)
├── README.md                     (full setup guide)
├── LICENSE                       (license text)
└── twitch_chat_bridge/
    ├── run.py                     (entry point for the bridge)
    ├── twitch_chat.config         (configuration – edit this)
    ├── twitch_token_helper.py     (generates persistent tokens)
    ├── twitch_session_persistence.json  (created after first run)
    ├── bridge/                    (main bridge logic)
    ├── database/                  (logging)
    ├── data/                      (log files)
    └── ...                        (other internal modules)

You only ever need to touch twitch_chat.config and, optionally, twitch_token_helper.py.

9. I get “Login authentication failed” when the bridge starts. Why?

Possible causes:

  • The token in twitch_chat.config or the session file is invalid/expired.
    Delete twitch_session_persistence.json and, if you have a static token in the config, ensure it is exactly oauth:xxxxxxxxxxxxx with no extra quotes.
  • The token has wrong permissions. The bot needs the chat:read and chat:edit scopes. If you generated the token manually, make sure these scopes were selected.
  • The token has been revoked. You can revoke all tokens from your Twitch Security settings and generate a new one.

Fix: Use the included token helper (twitch_token_helper.py) to generate a fresh token with the correct scopes. It will save a new session file automatically.

10. The bridge connects to Twitch but no messages appear in game.

Check these points:

  • RCON is enabled on your Factorio server. In factorio_server.config (or server-settings.json) you need rcon_port (not 0) and rcon_password set.
  • The RCON port/password match between the server and twitch_chat_bridge/twitch_chat.config.
  • The server has finished loading before the bridge tries to use RCON. The latest bridge version waits for the first chat message before connecting RCON, so this is rarely an issue now.
  • Firewall – if the bridge is on a different machine, ensure the RCON port is reachable.
  • Mod conflict? The bridge uses either the Better Chat mod’s remote interface or the fallback twitch_chat remote interface (provided by this mod). Make sure this mod is enabled on the server.

11. Can I use the bridge without this mod? I already have Better Chat.

Yes! The bridge tries to use Better Chat’s remote.call("better-chat", "send", ...) first. If that fails (Better Chat not installed), it falls back to this mod’s interface.
However, we recommend keeping this mod enabled as a safety net – it guarantees a working fallback.

12. Do I need a Twitch Client ID and Client Secret? What are they for?

They are optional but highly recommended.
If you provide a Client ID and Secret in twitch_chat.config, and enable twitch_token_refresh_enabled=true, the bridge will automatically refresh the access token when it expires. Without them, the access token will stop working after a few hours and you’ll have to generate a new one manually.
You can get these credentials by registering an application at dev.twitch.tv/console. It’s free and takes one minute.

13. How do I stop the bridge?

Press Ctrl+C in the console where the bridge (or the launcher) is running. The launcher’s built‑in handler will also stop the bridge when you close the server.
If you started the bridge in the background, find its PID and kill it, or use taskkill on Windows.

14. Will this mod affect my game performance?

No. The mod itself only registers a few slash commands and a remote interface – it uses negligible resources. The Python bridge runs externally and only sends one RCON command per chat message, which is extremely lightweight.

15. Can I customise the colours?

Yes. The Python bridge includes a colour formatter (twitch_factorio_chat_formatter.py). The default is:
- Broadcaster → red
- Moderator → green
- VIP → pink
- Subscriber → purple
- Turbo/Prime → blue
- Everyone else → white

You can edit that file to change any of the colours, or add rules for specific users.

16. What do I do if the bridge crashes or won’t start?

Check the logs first:
- Console output – the bridge prints detailed logs to the console.
- File log – twitch_chat_bridge/data/twitch_bridge_chat.log
- SQLite log – twitch_chat_bridge/data/twitch_bridge_log.db (can be viewed with any SQLite browser).

Common errors are:
- Missing Python packages → run pip install factorio-rcon-py irc requests --user
- Invalid config → ensure all required fields are filled, and no extra quotes around values.
- RCON connection refused → the Factorio server isn’t running or RCON isn’t enabled.

17. Can I run multiple bridges for different Twitch channels?

Yes. Each bridge instance connects to one Twitch channel. You would need to copy the twitch_chat_bridge folder, use a different config (and different RCON port if they are on the same machine), and run multiple python run.py processes.

18. Does this work with Twitch’s “Unique Chat” or “Followers‑only” modes?

The bridge is a regular IRC user, so it obeys the same restrictions as any other user in chat. If the channel is in followers‑only mode, the bot must be following the channel. If it’s in unique‑chat mode, the bridge will still relay all visible messages.

19. I want to uninstall everything. How?

  1. Stop the bridge and the server.
  2. Delete the twitch_chat_bridge/ folder from your server root.
  3. Delete Start-FactorioServer.ps1, README.md, and LICENSE if you don’t need them.
  4. Unsubscribe from the mod in the Factorio portal or delete the mod folder from %appdata%\Factorio\mods.

20. The mod description says “REQUIRES external Python bridge”. I’m a server admin, what do I tell my players?

Your players don’t need to do anything. The mod is required only on the server side. Players do not need to install the mod, subscribe to it, or run the bridge. They will simply see the chat messages appear in game when the bridge is running on the server.

21. I found a bug / have a feature request. Where can I report it?

Contact the maintainer via the information in the LICENSE file, or through the mod portal’s discussion page. When reporting, please include the log file (twitch_bridge_chat.log) if possible.

22. Is this mod open source? Can I modify it?

See the LICENSE file for terms. In short, personal use and modification are allowed under certain conditions. Redistribution or commercial use requires a separate agreement.
The source code of the Python bridge is fully visible after installation; you are free to inspect and adapt it for your personal server.

23. Why is the installer file called install_bridge.lua inside the mod? I thought it was Python.

The Factorio mod portal automatically scans for executable files and rejects them. By naming it .lua, we “hide” it from the scanner. It’s still plain text Python code – just renamed.
You must rename it back to .py to run it with Python. There is no Lua in that file at all.

24. I renamed it back to .py but Windows still shows it as a Lua file? Help!

Windows hides file extensions by default. You may have a file named install_bridge.py.lua by accident. Make sure file extensions are visible in Explorer (View → File name extensions) and rename it to just install_bridge.py.
In PowerShell, use:

Rename-Item install_bridge.lua install_bridge.py

This bypasses the Explorer confusion.

25. Can I just run the bridge on the same machine as my Factorio client (non‑dedicated)?

Yes, but the Factorio client does not expose RCON. You would need to use a dedicated server (headless) or a hosted server that provides RCON access. The bridge requires RCON.

26. I’m using a cloud hosting service for Factorio. Can I use this?

If your host provides RCON access (IP and port), then yes. Upload the installer script to the server, run it remotely (via SSH or a web terminal), and configure the bridge to use the host’s RCON details. The bridge can run on any machine that can reach the RCON port.

27. Nothing works. I’m pulling my hair out.

Deep breath. Follow this checklist:

  1. Did you rename install_bridge.lua to install_bridge.py and run it with Python?
  2. Did you edit twitch_chat_bridge/twitch_chat.config with real values?
  3. Is the Factorio server running and fully loaded?
  4. Is RCON enabled on the server (check factorio_server.config)?
  5. Did you start the bridge after the server was ready?
  6. Did you send a chat message in Twitch to trigger the first RCON connection?
  7. Check the logs (twitch_chat_bridge/data/twitch_bridge_chat.log). What do they say?

If you’re still stuck, gather the logs and reach out for support.

Terms of Service|Privacy|Imprint|Presskit|Contact|FAQ|Jobs
Copyright © 2015 - 2026 Wube Software - all rights reserved.