Metadata-Version: 2.1
Name: minpiler
Version: 0.3.0
Summary: Compile python code to Mindustry microprocessor instructions
Home-page: https://github.com/neumond/minpiler
Author: Vitalik Verhovodov
Author-email: knifeslaughter@gmail.com
License: MIT
Keywords: mindustry
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Topic :: Games/Entertainment
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: dataclasses ; python_version <= "3.6"

# Minpiler

Allows easier control over Mindustry microprocessors.
You can write _subset_ of Python instead assembler-like Mindustry instructions.
Consider this as effort to reuse Python syntax, rather than Python implementation.

**Warning**: Everything that requires dynamic memory doesn't work:
any data structure (list, dict, etc), classes, closures,
recursion. Additionally you can't use any Python builtins
(input, eval, Exception, etc). Imports do nothing, use it make flake8 happy.
Explanation below.

## Rationale

Mindustry microprocessors are quite nice and easy to understand.
They have explicit limit of instructions per unit of time.
They can operate on floats, refer to _objects_
(null, constant strings, @-objects, in-game units)
and fire several commands that affect the game.

Here is an example program that switches unloader output
between lead and titanium depending on time:

```
read time cell1 0
op add time time 1
jump 4 lessThan time 300
set time 0
write time cell1 0
jump 8 greaterThan time 200
control configure unloader1 @titanium
end
control configure unloader1 @lead
```

This program is fairly simple, but if you insert any instruction in
the middle of program, you have to rewrite many `jump` addresses.

What if you want to calculate some formula, let's say

```
2 + a * 2 + b + c * d * 3
```

You'll have to write:

```
op mul _r1 a 2
op add _r2 2 _r1
op add _r3 _r2 b
op mul _r4 c d
op mul _r5 _r4 3
op add result _r3 _r5
```

It becomes boring, error-prone and quite hard to modify.

What if you could write the following instead:

```python
time = cell1[0]
time += 1
if time >= 300:
    time = 0
cell1[0] = time
unloader1.configure(M.at.lead if time > 200 else M.at.titanium)
```

```python
result = 2 + a * 2 + b + c * d * 3
```

It's possible with minpiler!

1. Write your code in subset of Python
2. Compile it into Mindustry instructions
3. Copy the result into clipboard
4. Import code right into running game

So far so good, looks like you can just write Python code
and then import it into the game. As a good Pythonista you're eager to
use your knowledge of closures, classes and decorators to program
Mindustry controllers, but unfortunately I have to stop you there.
You won't be able to use most of the Python. All the restrictions
arise from Mindustry processor architecture:

1. There's no data structures, only scalar values are allowed (floats or opaque _objects_). The only exception are Memory cells that behave as fixed-size arrays of floats.
2. You can't access variables indirectly, there're no pointers, no `getattr`.
3. Subsequence of former, it's impossible to implement dynamic memory/stack (at least without Memory cells). This makes lists, iterators, classes, closures and other things impossible.
4. Set of builtins is very restricted, you can only call what you have available in game (M.print, M.draw.clear, etc)

Anyway, I hope Minpiler will be handy enough for you to have lots of fun playing Mindustry.

## How to use

```sh
# Install packages
pip install minpiler pyperclip

# Compile your code into clipboard
python -m minpiler --clip yourfile.py
# now open processor building, press Edit button, Import from Clipboard
```

Pyperclip is optional, it's only used with `--clip` option.

Refer to set of code [samples](samples/) in this repository.

## Compatibility

Python >= 3.6 or compatible pypy3.

Mindustry: currently only 121 have been tested.


