This is a program that allows twitch chat to control a pc. It's the core code for [this](https://www.twitch.tv/controlmypc). It features discord integration, permissions, a command processor, and everything you could need. It's fairly simple at its core, so don't be afraid to dive into the code :)
This is a program that allows twitch chat to control a pc. It's the core code for [this](https://www.twitch.tv/controlmypc). It features discord integration, permissions, a command processor, offline script testing, and everything you could need. It's fairly simple at its core, so don't be afraid to dive into the code :)
# script
# Script
The script is based off of dougdougw's script which is based off [this tutorial for creating a Twitch Plays stream](http://www.wituz.com/make-your-own-twitch-plays-stream.html). It was then rewritten by winnerspiros, then kae and again by jmcb.
The script is based off of dougdougw's twitchplays [script](https://www.dougdougw.com/twitch-plays-code) which is based off [this tutorial for creating a Twitch Plays stream](http://www.wituz.com/make-your-own-twitch-plays-stream.html). It was then rewritten by winnerspiros (winnerspiros#0152) to form 2.0.0, then again by Kae (Kae#0004) to form v3.0.0, and finally again by JMcB to form v3.X.X +. More documentation can be found [here](https://gitlab.com/controlmypc/TwitchPlays).
It's written in Python and mainly edited by max and joel, if you want to add something, you should probably ask them,
I'll probably add more documentation here later, but it's pretty simple, theres a seperate readme in that repo for more information.
In this house we follow [PEP 8](https://www.python.org/dev/peps/pep-0008/), the official Python style guide. (we really dont but we try to, just trust the intel [OK thanks max speak for urself])
-`--offline-mode <arg>` (optional) | Starts the script in offline mode, which lets you test the script from the command line.
## quote marks
In the case of [string quotes](https://www.python.org/dev/peps/pep-0008/#string-quotes)**we choose to use 'single quotes'** over "double quotes". Please stick to this rule. However, PEP 8 specifies to use the opposite kind of quote if a quote mark features in the string - to avoid escaping those characters with backslashes - and that that double quotes should always be used for """triple-quoted strings""".
## Code Consistency
## braces
The TwitchPlays script uses [PEP 8](https://www.python.org/dev/peps/pep-0008/), the official Python style guide.
We use the
## Quote Marks
In the case of [string quotes](https://www.python.org/dev/peps/pep-0008/#string-quotes), **we choose to use 'single quotes'** over "double quotes". Please stick to this rule. However, PEP 8 specifies to use the opposite kind of quote if a quote mark features in the string to avoid escaping those characters with backslashes. Double quotes should always be used for """triple-quoted strings""".
## Lists and Arrays
We use the following format for lists/arrays.
```python
```python
my_list=[
my_list=[
1,2,3,
1,2,3,
4,5,6,
4,5,6,
]
]
```
```
format.
# version number
## Version Number
The script (for the most part) follows [semver](https://semver.org)(short for semantic versioning) where each part of the version number has a specific meaning. For our script, we use the following format:
The script (for the most part) follows [semver](https://semver.org)(short for semantic versioning) where each part of the version number has a specific meaning. For our script, we use the following format:
```
```
[season number].[major or medium changes].[minor changes or bug fixes]
[season number + 1].[major or medium changes].[minor changes or bug fixes]
^ section 1 ^ section 2 ^ section 3
^ section 1 ^ section 2 ^ section 3
```
```
...
@@ -40,56 +41,50 @@ When one of these parts is increased, the ones following it must be set to zero.
...
@@ -40,56 +41,50 @@ When one of these parts is increased, the ones following it must be set to zero.
"Major or medium changes" are things like adding, removing, or changing important parts of a command (for example, making a new command or changing the arguments of an existing command). "Minor changes or bug fixes" are things like adding or changing features that don't directly affect commands or fixing small to medium size bugs in the script or commands (for example, the recent Unicode bug in the type command falls under this category).
"Major or medium changes" are things like adding, removing, or changing important parts of a command (for example, making a new command or changing the arguments of an existing command). "Minor changes or bug fixes" are things like adding or changing features that don't directly affect commands or fixing small to medium size bugs in the script or commands (for example, the recent Unicode bug in the type command falls under this category).
# error logging
## Error Logging
The script uses [Sentry](https://sentry.io) to log and keep track of errors throughout each release.
The script uses [Sentry](https://sentry.io) to log and keep track of errors throughout each release.
Sentry logging is automatically disabled for non-production environments unless `force_sentry_enabled` is `True` in `config.toml`. For production environments, the `sentry_enabled` setting in `config.toml` will enable or disable Sentry logging.
Sentry logging is automatically disabled for non-production environments unless `force_sentry_enabled` is `True` in `config.toml`. For production environments, the `sentry_enabled` setting in `config.toml` will enable or disable Sentry logging.
# requirements
## Updating requirements.txt
It's pretty simple to understand, you only have to install a few packages, most of them are either file imports or part of the python standard library.
You will mainly only need to install:
- pydirectinput - windows mouse movement
- pyautogui - dual platform (main handler)
- requests - api and discord webhook
- pynput - misc computer control
- toml - configuration
****When running the script, you may need to start it as a admin.****
## updating requirements.txt
Adhering to best practices, we include version numbers in our [requirements file](https://gitlab.com/controlmypc/TwitchPlays/-/blob/master/requirements.txt) in the format package==x.x.x
Adhering to best practices, we include version numbers in our [requirements file](https://gitlab.com/controlmypc/TwitchPlays/-/blob/master/requirements.txt) in the format package==x.x.x
Easy way to add new requirement:
-Easy way to add new requirement:
When you `pip install package`, note the version number and include it in your addition to requirements.txt
When you `pip install package`, note the version number and include it in your addition to requirements.txt
More complicated but more elegant way:
- More complicated but more elegant way:
Create and activate a virtualenv (Windows)
Create and activate a virtualenv (Windows)
```
```
python -m venv ".venv"
python -m venv ".venv"
.venv\Scripts\activate.bat
.venv\Scripts\activate.bat
```
```
(Mac and Linux)
(Mac and Linux)
```shell
```shell
python -m venv ".venv"
python -m venv ".venv"
source .venv/bin/activate
source .venv/bin/activate
```
```
Install existing requirements
Install existing requirements
```shell
```shell
pip install-r requirements.txt
pip3install-r requirements.txt
```
```
Install new requirement
Install new requirement
```shell
```shell
pip install package
pip3install package
```
```
And finally create the new requirements file with your new requirement included
And finally create the new requirements file with your new requirement included
```shell
```shell
pip freeze > requirements.txt
pip3 freeze > requirements.txt
```
```
# commands
## Commands
## categories
### Categories
Commands can be separated into categories:
Commands can be separated into categories:
...
@@ -101,28 +96,28 @@ Commands can be separated into categories:
...
@@ -101,28 +96,28 @@ Commands can be separated into categories:
- Mouse move commands
- Mouse move commands
- Mouse drag commands
- Mouse drag commands
- Commands that take arguments
- Commands that take arguments
- Type {text} commands
- Type <text> commands
- Hold key for {time} commands
- Hold key for {time} commands
- Misc commands
- Misc commands
- !modalert
- !modalert
- go to {x} {y}
- go to <x><y>
- gtype {text} (uses pydirectinput to type for greater video game compatability)
- gtype <text> (uses pydirectinput to type for greater video game compatability)
- Commands that any viewers can run
- Commands that any viewers can run
- Commands that are exclusive to certain users
- Commands that are exclusive to certain users
- Commands that only devs can run
- Commands that only developers can run
- Commands that only mods can run
- Commands that only moderators can run
- Commands that are exclusive to one certain user
- Commands that are exclusive to one certain user
- Commands that only cmpcscript can run
- Commands that only the account `cmpcscript` can run
The order of the commands within the script should roughly match the order of the commands on the [command list on the website](https://cmpc.live/commands/)[(source)](https://gitlab.com/controlmypc/web/-/blob/master/commands/index.html). This makes it easier to ensure the lists match.
The order of the commands within the script should roughly match the order of the commands on the [command list on the website](https://cmpc.live/commands/)[(source)](https://gitlab.com/controlmypc/web/-/blob/master/commands/index.html). This makes it easier to ensure the lists match.
In the future, we maybe should consider generating a list of commands using the script for that purpose.
In the future, we maybe should consider generating a list of commands using the script for that purpose.
## restricted commands
## Restricted Commands
These commands are not listed on the website and are therefore documented here instead.
These commands are not listed on the website and are therefore documented here instead.
Dev only commands
Developer only commands
script- testconn (sends a test message to the modtalk webhook)
script- testconn (sends a test message to the modtalk webhook)
script- reqdata (sends data about current runtime vars to the modtalk webhook)
script- reqdata (sends data about current runtime vars to the modtalk webhook)
script- apirefresh (reloads the devs and mods lists from the API)
script- apirefresh (reloads the devs and mods lists from the API)
...
@@ -130,17 +125,17 @@ script- forceerror (sends a test error to the systemlog webhook)
...
@@ -130,17 +125,17 @@ script- forceerror (sends a test error to the systemlog webhook)
modsay {message} (sends the message to the modtalk webhook)
modsay {message} (sends the message to the modtalk webhook)
chatbot- {signal} (sends a signal input to dukt hosting)
chatbot- {signal} (sends a signal input to dukt hosting)
Mod only commands
Moderator only commands
modsay {message} (see dev only commands)
modsay {message} (see dev only commands)
cmpcscript
User `cmpcscript`
If the user is cmpcscript this will be logged and if cmpcscript's message matches the *key* then the script will shut down with `exit(1)`
If the user is cmpcscript this will be logged and if cmpcscript's message matches the *key* then the script will shut down with `exit(1)`
# legacy restrictions
## Legacy Restrictions
It has been put in place that toml will remain the standard configuration format for the script.
It has been put in place that toml will remain the standard configuration format for the script.
It has also been motioned and put into place, that the twitch vars should not change within the toml file, if something is added to the toml, it can be, but nothing should ever be removed.
It has also been motioned and put into place, that the twitch vars should not change within the toml file, if something is added to the toml, it can be, but nothing should ever be removed.
# testing
## Testing
To run the script follow the instructions in the [readme](https://gitlab.com/controlmypc/TwitchPlays/-/blob/master/README.md).
To run the script follow the instructions in the [readme](https://gitlab.com/controlmypc/TwitchPlays/-/blob/master/README.md).
...
@@ -168,19 +163,19 @@ Add the variable
...
@@ -168,19 +163,19 @@ Add the variable
export TWITCH_OAUTH_TOKEN="xxxxxxxxxxxxxxxxxx"
export TWITCH_OAUTH_TOKEN="xxxxxxxxxxxxxxxxxx"
```
```
## input monitors
## Input Monitors
The scripts in the testing directory are useful for testing. Just run them and they'll print out every new keyboard or mouse input, respectively. You can use them to verify that the script is creating the correct inputs with pyautogui.
The scripts in the testing directory are useful for testing. Just run them and they'll print out every new keyboard or mouse input, respectively. You can use them to verify that the script is creating the correct inputs with pyautogui.
## obs with executing.txt
## OBS with executing.txt
If you want to test the functionality of log_to_obs, you have to install [this plugin](https://obsproject.com/forum/attachments/obs-text-zip.56495/), taken from [this forum post](https://obsproject.com/forum/threads/read-from-text-file-refresh-rate.73589/post-460054). Instructions for installation are in the forums post. The purpose of the plugin is to make text file sources refresh at the rate necessary for this application.
If you want to test the functionality of log_to_obs, you have to install [this plugin](https://obsproject.com/forum/attachments/obs-text-zip.56495/), taken from [this forum post](https://obsproject.com/forum/threads/read-from-text-file-refresh-rate.73589/post-460054). Instructions for installation are in the forums post. The purpose of the plugin is to make text file sources refresh at the rate necessary for this application.
Then, in OBS go to `Sources -> + -> Text (GDI+)`, toggle the `Read from file` option on, and select `executing.txt` as the file.
Then, in OBS go to `Sources -> + -> Text (GDI+)`, toggle the `Read from file` option on, and select `executing.txt` as the file.
If you want emojis to show up, you'll have to change the settings of the `Text (GDI+)` to a font that supports them, e.g. Segoe UI Emoji.
If you want emojis to show up, you'll have to change the settings of the `Text (GDI+)` to a font that supports them, e.g. Segoe UI Emoji.
## conditions on the shadow (mostly gpedit)
## Conditions on the Shadow (mostly gpedit)
cmpc has the command prompt disabled on the shadow for security purposes. If you want to test code related to this, you'll need to replicate it.
CMPC has the command prompt disabled on the shadow for security purposes. If you want to test code related to this, you'll need to replicate it.
