# Stormworks Microcontroller framework
A framework for building microcontrollers in Stormworks: Build and Rescue using python scripts.
## Features
- Modular design: Easily create and manage multiple microcontroller scripts.
- Latency optimization: Arithmetic functions are collapsed into function blocks in order to reduce latency.
- Auto layout: Automatically arrange function blocks for better readability.
- Integration with `tumfl` for lua verification and minification.
- Implicit constant number creation.
## Getting started
### Installation
#### Install the package using pip
```commandline
pip install sw_mc_builder
```
#### Install using prebuilt binaries
Copy the latest release for your platform from the [releases](https://github.com/stormworks-utils/sw_mc_builder/releases) page and add it to your PATH.
### Usage
After installing, use the `sw_mc_builder` module/executable to create microcontrollers.
```commandline
sw_mc_builder init test_mc.py
```
Afterwards, you can define a microcontroller in `test_mc.py`.
```python
from sw_mc_builder import *
input1 = comp.input(SignalType.Number, "Input 1")
input2 = comp.input(SignalType.Number, "Input 2")
added = input1 + input2 * 2
highest = input1.max(input2)
mc = Microcontroller("Example MC")
mc.place_input(input1, 0, 0)
mc.place_input(input2, 0, 1)
mc.place_output(added, "Added", x=1, y=0)
mc.place_output(highest, "Highest", x=1, y=1)
if __name__ == "__main__":
handle_mcs(mc)
```
And finally, run the script to generate the microcontroller (`-m`).
```commandline
sw_mc_builder run test_mc.py -m
```
## Design
There are two predominant design patterns used in this framework:
### Python operators
```python
from sw_mc_builder import *
input1 = comp.input(SignalType.Number, "Input 1")
input2 = comp.input(SignalType.Number, "Input 2")
added = input1 + input2
maxed = (added * input2).max(1)
```
Each operation is represented as a python expression. This makes it very easy to write and read code,
but latency is harder to reason about, as some operations can result in multiple components.
> [!WARNING]
> There are some operands which are impossible to implement as python expressions, see below.
### Component functions
```python
from sw_mc_builder import *
input1 = comp.input(SignalType.Number, "Input 1")
input2 = comp.input(SignalType.Number, "Input 2")
added = comp.add(input1, input2)
multiplied = comp.mul(added, input2)
maxed = comp.function("max(x,y)", multiplied, 1)
```
Each function represents exactly one component. This makes latency very easy to reason about, as each function has a
fixed latency of one tick.
> [!WARNING]
> The optimizer might collapse multiple arithmetic operations into a single function block, which can affect latency.
> [!INFO]
> It is discouraged to use numerical or boolean function blocks. In part due to the poor readability,
> but also because some parts of the optimizer work better, if there are no function blocks.
### Caveats of using python operators
- `and`: Use `&` instead. Keep in mind that `&` has a different operator precedence than `and`.
- `or`: Use `|` instead. Keep in mind that `|` has a different operator precedence than `or`.
- `not`: Use `~` instead. Keep in mind that `~` has a different operator precedence than `not`.
- `int`: Use `<Wire>.int()` instead. Will convert a boolean to a number (0 or 1).
- `__getindex__`: (`<Wire>[index]`): will always return a number. If you want to get a boolean, use
`<Wire>.get_bool(index)` instead.
- `__setindex__`: (`<Wire>[index] = value`): This will create a new composite write for each write.
### Functions other than python operators
The `Wire` class has a few functions that are possible with function blocks.
- `max(other)`: Maximum of two wires.
- `min(other)`: Minimum of two wires.
- `clamp(min, max)`: Clamp the wire between min and max.
- `lerp(start, end)`: Linear interpolation between two wires.
- `sin()`: Sine of the wire (in radians).
- `cos()`: Cosine of the wire (in radians).
- `tan()`: Tangent of the wire (in radians).
- `asin()`: Arcsine of the wire (in radians).
- `acos()`: Arccosine of the wire (in radians).
- `atan()`: Arctangent of the wire (in radians).
- `atan2(other)`: Arctangent of the wire and another wire (in radians).
- `sqrt()`: Square root of the wire.
- `ceil()`: Ceiling of the wire.
- `floor()`: Floor of the wire.
- `round(ndigits)`: Round the wire.
- `sgn()`: Sign of the wire.
- `switch(on_wire, off_wire)`: Switch between two wires based on the boolean value of the wire.
## Working principles
### Microcontroller handler
The `handle_mcs` function is the entity that will bring your microcontrollers to life.
It manages the actual generation (including optimization and layout) and placement of microcontrollers.
It can replace existing microcontrollers in vehicles, or simply make them available ingame.
It can handle multiple microcontrollers at once.
#### Command line arguments
- `-m` or `--microcontroller`: Export generated microcontrollers to the games microcontrollers directory.
- `-v` or `--vehicle`: Replace microcontrollers in vehicles in the games vehicles directory. Will reserve parameter settings.
- `-s` or `--select`: Only process microcontrollers with the given, comma separated, names.
### Recursive definitions
There is a special component, a `Placeholder`, which can be used to create recursive definitions.
A `Placeholder` must be resolved before submitting the microcontroller to `handle_mcs`, otherwise an error will be raised.
```python
from sw_mc_builder import *
counter = comp.placeholder(SignalType.Number)
counter.replace_producer(counter + 1)
```
### Input and output management
Inputs will usually be the first thing to be defined in a microcontroller. They produce `Wire` objects that can be used in the microcontroller.
If an input is used in any calculation that is present in an output, wi has to be placed in the microcontroller.
Outputs are simply defined by placing them in a microcontroller.
If inputs or outputs are outside of the boundaries of the microcontroller, a warning will be generated, and the microcontroller expanded.
```python
from sw_mc_builder import *
input1 = comp.input(SignalType.Number, "Input 1")
input2 = comp.input(SignalType.Number, "Input 2")
# Program logic
added = input1 + input2 * 2
mc = Microcontroller("Example MC")
mc.place_input(input1, 0, 0)
mc.place_input(input2, 0, 1)
mc.place_output(added, "Added", x=1, y=0)
if __name__ == "__main__":
handle_mcs(mc)
```
### Optimizer
All arithmetic operations are collapsed into a single function block in order to reduce latency.
This can be disabled per node or per mc.
```python
from sw_mc_builder import *
input1 = comp.input(SignalType.Number, "Input 1")
# Delay signal by one tick, disabling optimization for this node
delayed = comp.function("x", input1).stop_optimization()
# Disable optimization for the entire microcontroller
mc = Microcontroller("name")
mc.stop_optimization()
```
### Microcontroller thumbnails
Microcontroller thumbnails can either be included as a `.png` file using `mc.add_image_from_file(Path("path/to/thumbnail.png"))`,
or be written as a list of lists of booleans using `mc.add_image_from_list(image_data)`.
Note: Images will automatically be resized to 16x16 pixels and converted to black and white.
Raw data
{
"_id": null,
"home_page": null,
"name": "sw-mc-builder",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "stormworks, microcontroller, builder, automation",
"author": "Fabian Wunsch",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/18/94/a3b8749f71cec6a752fcd8f90905f9a5038e897fc18cdc8784259c7a545c/sw_mc_builder-0.1.5.tar.gz",
"platform": null,
"description": "# Stormworks Microcontroller framework\n\nA framework for building microcontrollers in Stormworks: Build and Rescue using python scripts.\n\n## Features\n\n- Modular design: Easily create and manage multiple microcontroller scripts.\n- Latency optimization: Arithmetic functions are collapsed into function blocks in order to reduce latency.\n- Auto layout: Automatically arrange function blocks for better readability.\n- Integration with `tumfl` for lua verification and minification.\n- Implicit constant number creation.\n\n## Getting started\n\n### Installation\n\n#### Install the package using pip\n\n```commandline\npip install sw_mc_builder\n```\n\n#### Install using prebuilt binaries\n\nCopy the latest release for your platform from the [releases](https://github.com/stormworks-utils/sw_mc_builder/releases) page and add it to your PATH.\n\n### Usage\n\nAfter installing, use the `sw_mc_builder` module/executable to create microcontrollers.\n\n```commandline\nsw_mc_builder init test_mc.py\n```\n\nAfterwards, you can define a microcontroller in `test_mc.py`.\n\n```python\nfrom sw_mc_builder import *\n\ninput1 = comp.input(SignalType.Number, \"Input 1\")\ninput2 = comp.input(SignalType.Number, \"Input 2\")\n\nadded = input1 + input2 * 2\nhighest = input1.max(input2)\n\nmc = Microcontroller(\"Example MC\")\nmc.place_input(input1, 0, 0)\nmc.place_input(input2, 0, 1)\nmc.place_output(added, \"Added\", x=1, y=0)\nmc.place_output(highest, \"Highest\", x=1, y=1)\n\nif __name__ == \"__main__\":\n handle_mcs(mc)\n```\n\nAnd finally, run the script to generate the microcontroller (`-m`).\n\n```commandline\nsw_mc_builder run test_mc.py -m\n```\n\n## Design\n\nThere are two predominant design patterns used in this framework:\n\n### Python operators\n\n```python\nfrom sw_mc_builder import *\n\ninput1 = comp.input(SignalType.Number, \"Input 1\")\ninput2 = comp.input(SignalType.Number, \"Input 2\")\n\nadded = input1 + input2\nmaxed = (added * input2).max(1)\n```\n\nEach operation is represented as a python expression. This makes it very easy to write and read code,\nbut latency is harder to reason about, as some operations can result in multiple components.\n> [!WARNING]\n> There are some operands which are impossible to implement as python expressions, see below.\n\n### Component functions\n\n```python\nfrom sw_mc_builder import *\n\ninput1 = comp.input(SignalType.Number, \"Input 1\")\ninput2 = comp.input(SignalType.Number, \"Input 2\")\n\nadded = comp.add(input1, input2)\nmultiplied = comp.mul(added, input2)\nmaxed = comp.function(\"max(x,y)\", multiplied, 1)\n```\n\nEach function represents exactly one component. This makes latency very easy to reason about, as each function has a\nfixed latency of one tick.\n\n> [!WARNING]\n> The optimizer might collapse multiple arithmetic operations into a single function block, which can affect latency.\n\n> [!INFO]\n> It is discouraged to use numerical or boolean function blocks. In part due to the poor readability,\n> but also because some parts of the optimizer work better, if there are no function blocks.\n\n### Caveats of using python operators\n\n - `and`: Use `&` instead. Keep in mind that `&` has a different operator precedence than `and`.\n - `or`: Use `|` instead. Keep in mind that `|` has a different operator precedence than `or`.\n - `not`: Use `~` instead. Keep in mind that `~` has a different operator precedence than `not`.\n - `int`: Use `<Wire>.int()` instead. Will convert a boolean to a number (0 or 1).\n - `__getindex__`: (`<Wire>[index]`): will always return a number. If you want to get a boolean, use\n `<Wire>.get_bool(index)` instead.\n - `__setindex__`: (`<Wire>[index] = value`): This will create a new composite write for each write.\n\n### Functions other than python operators\n\nThe `Wire` class has a few functions that are possible with function blocks.\n\n- `max(other)`: Maximum of two wires.\n- `min(other)`: Minimum of two wires.\n- `clamp(min, max)`: Clamp the wire between min and max.\n- `lerp(start, end)`: Linear interpolation between two wires.\n- `sin()`: Sine of the wire (in radians).\n- `cos()`: Cosine of the wire (in radians).\n- `tan()`: Tangent of the wire (in radians).\n- `asin()`: Arcsine of the wire (in radians).\n- `acos()`: Arccosine of the wire (in radians).\n- `atan()`: Arctangent of the wire (in radians).\n- `atan2(other)`: Arctangent of the wire and another wire (in radians).\n- `sqrt()`: Square root of the wire.\n- `ceil()`: Ceiling of the wire.\n- `floor()`: Floor of the wire.\n- `round(ndigits)`: Round the wire.\n- `sgn()`: Sign of the wire.\n- `switch(on_wire, off_wire)`: Switch between two wires based on the boolean value of the wire.\n\n## Working principles\n\n### Microcontroller handler\n\nThe `handle_mcs` function is the entity that will bring your microcontrollers to life.\nIt manages the actual generation (including optimization and layout) and placement of microcontrollers.\nIt can replace existing microcontrollers in vehicles, or simply make them available ingame.\nIt can handle multiple microcontrollers at once.\n\n#### Command line arguments\n\n - `-m` or `--microcontroller`: Export generated microcontrollers to the games microcontrollers directory.\n - `-v` or `--vehicle`: Replace microcontrollers in vehicles in the games vehicles directory. Will reserve parameter settings.\n - `-s` or `--select`: Only process microcontrollers with the given, comma separated, names.\n\n### Recursive definitions\n\nThere is a special component, a `Placeholder`, which can be used to create recursive definitions.\nA `Placeholder` must be resolved before submitting the microcontroller to `handle_mcs`, otherwise an error will be raised.\n\n```python\nfrom sw_mc_builder import *\n\ncounter = comp.placeholder(SignalType.Number)\ncounter.replace_producer(counter + 1)\n```\n\n### Input and output management\n\nInputs will usually be the first thing to be defined in a microcontroller. They produce `Wire` objects that can be used in the microcontroller.\nIf an input is used in any calculation that is present in an output, wi has to be placed in the microcontroller.\n\nOutputs are simply defined by placing them in a microcontroller.\n\nIf inputs or outputs are outside of the boundaries of the microcontroller, a warning will be generated, and the microcontroller expanded.\n\n```python\nfrom sw_mc_builder import *\n\ninput1 = comp.input(SignalType.Number, \"Input 1\")\ninput2 = comp.input(SignalType.Number, \"Input 2\")\n\n# Program logic\nadded = input1 + input2 * 2\n\nmc = Microcontroller(\"Example MC\")\nmc.place_input(input1, 0, 0)\nmc.place_input(input2, 0, 1)\nmc.place_output(added, \"Added\", x=1, y=0)\n\nif __name__ == \"__main__\":\n handle_mcs(mc)\n```\n\n### Optimizer\n\nAll arithmetic operations are collapsed into a single function block in order to reduce latency.\nThis can be disabled per node or per mc.\n\n```python\nfrom sw_mc_builder import *\n\ninput1 = comp.input(SignalType.Number, \"Input 1\")\n\n# Delay signal by one tick, disabling optimization for this node\ndelayed = comp.function(\"x\", input1).stop_optimization()\n\n# Disable optimization for the entire microcontroller\nmc = Microcontroller(\"name\")\nmc.stop_optimization()\n```\n\n### Microcontroller thumbnails\n\nMicrocontroller thumbnails can either be included as a `.png` file using `mc.add_image_from_file(Path(\"path/to/thumbnail.png\"))`,\nor be written as a list of lists of booleans using `mc.add_image_from_list(image_data)`.\n\nNote: Images will automatically be resized to 16x16 pixels and converted to black and white.\n",
"bugtrack_url": null,
"license": null,
"summary": "Framework for building Stormworks microcontrollers",
"version": "0.1.5",
"project_urls": {
"homepage": "https://github.com/stormworks-utils/sw_mc_builder",
"repository": "https://github.com/stormworks-utils/sw_mc_builder"
},
"split_keywords": [
"stormworks",
" microcontroller",
" builder",
" automation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c89f1b5bf4880252bcd987da887f280888a6a1e4e726c8590cbaf616059b09ea",
"md5": "281f864fcc2f56d1b326725a024e9e32",
"sha256": "7ff92bbab27f7dd2a59b99c3bbd3c72ccd999c3a02df77170a396d389191f7c1"
},
"downloads": -1,
"filename": "sw_mc_builder-0.1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "281f864fcc2f56d1b326725a024e9e32",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 29048,
"upload_time": "2025-10-12T18:51:47",
"upload_time_iso_8601": "2025-10-12T18:51:47.800633Z",
"url": "https://files.pythonhosted.org/packages/c8/9f/1b5bf4880252bcd987da887f280888a6a1e4e726c8590cbaf616059b09ea/sw_mc_builder-0.1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1894a3b8749f71cec6a752fcd8f90905f9a5038e897fc18cdc8784259c7a545c",
"md5": "c056ab95e3f0664d2b5442a5642ed7e3",
"sha256": "1f5d69d3a44d62cc28dda7114f9ead2e6ec7ad864d928cb0449691c8236814da"
},
"downloads": -1,
"filename": "sw_mc_builder-0.1.5.tar.gz",
"has_sig": false,
"md5_digest": "c056ab95e3f0664d2b5442a5642ed7e3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 28158,
"upload_time": "2025-10-12T18:51:49",
"upload_time_iso_8601": "2025-10-12T18:51:49.014012Z",
"url": "https://files.pythonhosted.org/packages/18/94/a3b8749f71cec6a752fcd8f90905f9a5038e897fc18cdc8784259c7a545c/sw_mc_builder-0.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-12 18:51:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "stormworks-utils",
"github_project": "sw_mc_builder",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [
{
"name": "pillow",
"specs": [
[
"==",
"11.3.0"
]
]
},
{
"name": "sw-mc-lib",
"specs": [
[
"==",
"0.4.13"
]
]
},
{
"name": "tumfl",
"specs": [
[
"==",
"0.3.14"
]
]
},
{
"name": "watchdog",
"specs": [
[
"==",
"6.0.0"
]
]
}
],
"lcname": "sw-mc-builder"
}
JSON
