mindustry-c: A JavaScript program compiling C code to Mindustry Assembly

中文 README（更新可能有延迟）

What is Mindustry-C?

Current Plan

Incomplete parts:

• Comprehensive testing (will be done as I occasionally use it)

---

Please notice that: Mindustry-C has AI-generated code. The AI tool used in this project is DeepSeek (for individuals).

I have no time to code completely, though. I've written only prompts and some parts of code (including 100% part of code generation part (i.e. mindcGenerator*.js) and almost 60% of optimizer (i.e. mindcOptimizer.js)) for it. (Yet for sure, I also have to do all bug-fixing.) (AI is just no so realiable as I've expected)

• This piece of text is clarified on 19 Mar.

Mindustry-C aims to compile C code to Mindustry Assembly, a brain-racking language for most of us.

There have been many similar softwares aiming at using languages like C/C++ (alike grammar) or Python to code in Mindustry, but they aren't so effective. So here we are.

Installation

Installation is not needed. Just download main.html and all javascript files and ensure that you have Internet connection (UI requires Bootstrap from CDN; or the display might be a little bit weird).

Then, start a server and browse main.html from it (or you will be blocked by CORS policy of browsers).

(If you use Windows, then start.bat can do these for you.)

Execute the following command in the root directory of the download files if you have python 3:

python -m http.server

Or if you want to make it 100% steambird-made.

For grammar introduction (about the features unique to Mindustry-C) and examples, refer to docs (might be in progress).

Features about Mindustry-C

• Most of C89 features

  • Yes, you'll have structs, pointers, unions, and typedef!
  • But you won't have #elif and VA_ARGS macro (#include and other preprocessor instructions has been added)
  • Also, support for function pointers might be limited

• Some C/C++ features:

  • Partial support for const and auto (used to describe automatically-connected devices)

• Adding special types for Mindustry:

  • device for device (conveyors, scatters, etc.)
  • null_t for null in Mindustry (notice that it might not like nullptr or (void*)0)

• Memory mapping (adjusted outside the code)

• Function call stack

• Mindustry "system calls"

  • Building control
  • Unit control

• Direct "assembly" insertion

• Compiler's optimizing

  • Compile-time constant evaluation
    • Including those in for or while loop (they won't be so efficient, though)!
  • Removal of unused code/variable
    • Including unused if branches or while loops
  • Inlining functions
  • There's no Loop unrolling (because instructions are expensive in Mindustry!)

Notice

1. Following functions rely on memory allocation:

• Any volatile variable
• Any variable that has address (&var)
• Any array (If you don't want to use memory but still want arrays, refer to pseudo list's documents to look for possible alternatives.)
• Any recursive function

2. If functions aren't called recursively, they does not take up memory space.

3. A pointer takes up 2 units of spaces, respectively storing the memory cell and address of the element it points to.

4. A union type takes up the same space and time (when copying) if stored in register.

Using heap memory might be costly. Avoid declaring memory-demanding variables (listed above) in non-main functions (place them in global scope instead). It is also strongly recommended to prevent using recursive functions. They are supported but unstable and costly as the compiler is unsure about every variable's state.

Arrays might also take up additional spaces to store its previous/next cell of storage. Designing memory structure for this strange "cyber-" hardware is hard.

An Overview of Special Grammar

Specialized for Mindustry

• device type is used to describe buildings/units in Mindustry while content_t is used to describe objects.
• Use auto device conveyor1; to register a connected device (auto is essential).
• Use extern to declare that this variable should be declared.
• Use (volatile int*) (or similar) to force to transmit registry variables to some functions (for builtin calls, especially ulocate).
• Function pointers must have a typedef to declare its type before being used.

Different from C/C++

• Initializer lists are recommended to be unwrapped and must be non-empty (or the compiler will crash!).