[Original README here: https://github.com/simon816/Command-Block-Assembly]

Command Block Assembly

Now with 99% less command blocks

Command Block Assembly is a tool that allows you to write assembly instructions that compile down into Minecraft commands.

With the introduction of Functions in Minecraft 1.12, Command Block Assembly now outputs functions. Functions greatly increase the speed of execution, so Command Block Assembly keeps the usage of command blocks to a minimum.

C Compiler

There is a C compiler that compiles to this assembly language, read more here.

The Assembly Language

It is a simple language with instructions similar to that of x86.

Syntax

Here's a description of the syntax in rough BNF:

<program> ::= <statement> | <whitespace> <statement> | <program> <program>
<statement> ::= (<directive> | <label> | <instruction> | <constant> | <comment>) <eol>
<directive> ::= "#" <symbol> <whitespace> <ANY> <line-end>
<label> ::= (<symbol> | "_" <symbol>) ":" (<instruction> | <line-end>)
<instruction> ::= (<symbol> | <symbol> <whitespace> <operands>) <line-end>
<operands> ::= <reference> | <reference> [<whitespace>] "," [<whitespace>] <operands>
<constant> ::= "." <symbol> <whitespace> <reference> <line-end>
<comment> ::= ";" <ANY> <eol>
<line-end> ::= <EOF> | <eol> | <comment>
<reference> ::= "#" <number> | <number> | <symbol> | <string>
<string> ::= '"' <ANY> '"'
<symbol> ::= <ident-start> | <ident-start> <identifier>
<ident-start> ::= <alpha> | "_"
<identifier> ::= <ident-start> | <decimal>
<number> ::= <decimal> | "0" "x" <hexadecimal> | "0" "o" <octal> | "0" "b" <binary>

<alpha> ::= "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M"
 | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z"
 | "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m"
 | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z"

<binary> ::= "0" | "1" | <binary> <binary>
<octal> ::= <binary> | "2" | "3" | "4" | "5" | "6" | "7" | <octal> <octal>
<decimal> ::= <octal> | "8" | "9" | <decimal> <decimal>
<hexadecimal> ::= <decimal> | "A" | "B" | "C" | "D" | "E" | "F"
 | "a" | "b" | "c" | "d" | "e" | "f" | <hexadecimal> <hexadecimal>
<whitespace> ::= " " | "\t" | <whitespace> <whitespace>

What this actually looks like:

#include foo.asm

; Useful comment

.my_const #1 ; A constant value
.my_ref my_const ; A constant reference

main:
 MOV #0x01, 0 ; Do the thing
 _loop: ADD my_const, 0
 JMP _loop

Instruction Set

ADD src, dest
Adds src to dest

SUB src, dest
Subtracts src from dest

MUL src, dest
Multiplies dest by src

DIV src, dest
Divides dest by src

MOD src, dest
Performs dest modulo src and puts into dest

MOVLT src, dest
Sets dest equal to src if src is less than dest

MOVGT src, dest
Sets dest equal to src if src is greater than dest

XCHG left, right
Exchanges left with right

MOV src, dest
Copies src to dest

AND src, dest
Performs bitwise AND, result put into dest

OR src, dest
Performs bitwise OR and puts into dest

XOR src, dest
Performs bitwise XOR and puts into dest

NOT ref
Performs bitwise NOT on ref

SHL src, dest
Logical shift dest left by src

SHR src, dest
Logical shift dest right by src

SAR src, dest
Arithmetic shift dest right by src

ROL src, dest
Rotates dest left by src

ROR src, dest
Rotates dest right by src

CMP left, right
Compares left with right (i.e. right - left), result used for jumping

JE label
Jumps to label if the previous CMP's operands were equal

JNE label
Jumps to label if the previous CMP's operands were not equal

JL label
Jumps to label if the previous CMP's right was less than left

JG label
Jumps to label if the previous CMP's right was greater than left

JLE label
Jumps to label if the previous CMP's right was less than or equal to the left

JGE label
Jumps to label if the previous CMP's right was greater than or equal to the left

JMP label
Unconditionally jumps to label

CALL label
Jumps to label, returns back after completion

RET
Return from a subroutine (use with CALL)

PRINT arg1, [...args]
Outputs arguments to chat for all players (@a selector)

CMD bare words
Runs the given command

TEST bare words
Runs the given command, skipping the next line if the command failed

PUSH

Pushes stack register onto the stack, increments stack pointer

POP
Pops stack into stack register, decrements stack pointer

SYNC
Synchronises with the game tick. i.e. wait one tick before continuing

Operand types

There are 2 'types' of referencing:

• Value reference
• Literal value (e.g. #42)
• Memory location (e.g. 0x000F)


• Label reference
• A subroutine name (e.g. main)

Constants must be a value reference, and can be used anywhere that accepts value references.

For the instructions above, their accepted types are as follows:

A src can be any value reference.
dest must be a memory location reference.

SWP's left and right must both be memory location references.
CMP's left and right can be any value reference.

A label must be a label reference.

"Bare words" are taken as the literal string value until the end of the line. Note that this means comments are interpreted as part of the bare word.

Constants

As shown in the syntax, constants are defined with "." followed by their name, a space, then the value.
Constants can only be value references, but can be any type of value reference.

There are two predefined constants:

sp (Stack pointer)
The current value of the stack pointer. Should be treated as read-only unless you know what you're doing.

sr (Stack register)
Used to get values to/from the stack.
POP puts the top of the stack into the register, PUSH puts stack register at the top of the stack.

Directives

Directives are a kind of meta-program language that instruct the assembler to perform certain functions.

The following directives are supported:

#include filename.asm

Pulls in code from filename.asm in-place. Has the same effect as copy+pasting all the code from the file into wherever the directive is.

#include_h filename.asm

"Include headers". Does not load any code from the file, but pulls in the symbol table (subroutines, constants).
Useful for using library code already running in the game. (i.e. library was loaded sometime beforehand).

Memory locations

Memory locations can be thought of like locations in RAM, however there are a few things you need to know.

You can't reference locations indirectly (e.g. pointers).
Locations are actually just scoreboard objectives, and are computed at compile-time. They are really only useful for storing temporary data and using as global names (like sp and sr).

It is not possible to dynamically reference scoreboard objectives (or function names, for that matter). So you can't do something like MOV #1, [loc] (move literal 1 to the address stored in loc).

The only way to have truly real memory is using something like hdd_driver (see examples) or a giant lookup table. (Something like if(addr==0) objective_0=buffer else if (addr==1) objective_1=buffer ...)
This is how the stack is implemented, it performs a lookup on the current sp value.

The Assembler

The assembler is invoked by calling main.py.

Command line parameters:

usage: main.py [-h] [--world-dir WORLD_DIR] [--namespace NAMESPACE]
 [--rem-existing] [--debug] [--stack STACK] [--arg ARG]
 [--jump JUMP] [--place-location PLACE_LOCATION] [--enable-sync]
 file

positional arguments:
 file ASM File

optional arguments:
 -h, --help show this help message and exit
 --world-dir WORLD_DIR
 World Directory
 --namespace NAMESPACE
 Function namespace
 --rem-existing Remove existing functions in namespace
 --debug Enable debug output
 --stack STACK Stack size
 --arg ARG ASM file arguments
 --jump JUMP Output subroutine jump instruction
 --place-location PLACE_LOCATION
 Location to place command blocks
 --enable-sync Enable SYNC opcode

Notes:

If --world-dir is not provided, no functions are written. This can be useful in combination with --debug.

--place-location is where to start laying out command blocks, should they be needed. Defaults to ~1,~,~1

--arg is used to pass values in to a program that get replaced in the output. They are currently only applicable in CMD and TEST instructions. e.g.

main: CMD say Hello $arg:name$! This was generated on $arg:date$

Running python main.py test.asm --debug --arg "name=Simon" --arg "date=24/10/2017" produces:

Function sub_main

  say Hello Simon! This was generated on 24/10/2017

Running a program

In order to run a subroutine (main is a good name for the entry point), you need to run the jump command.

e.g. to run a subroutine named main, use --jump main, this will output the exact command to run.

The first time a program is loaded into a world, the setup command must be ran before any function calls are made.
The setup command is outputted by the assembler.

The assembler also outputs a cleanup function, which performs the opposite operation to setup. If command blocks are placed by the setup command, the cleanup command will remove them. If a relative --place-location was used, the cleanup must be executed from the same location that setup was ran from.

Note: the /execute command is required for the subroutine jump. Don't be tempted to run /function directly.

Examples

Examples can be found in the examples directory.

fib.asm

Prints the fibonacci sequence until the next integer overflows.

hdd_driver.asm

An example of how the assembly code can make use of the world.

The "hard drive" is represented by blocks in the world. An air block represents 0, stone = 1.

In this example, data is stored in a 2D plane on the x and z axis.
A memory location loc is stored at x = loc / MEM_SIZE_X, z = loc % MEM_SIZE_Z
The value is then WORD_SIZE bits in the y axis. i.e. for an 8-bit word, y=0 is the LSB, y=7 is the MSB.

hdd_driver.asm is a library file, and exports the read_mem, write_mem subroutines along with its constants.

The location where the memory region is defined must be passed in to the assembler:
--arg "mem_loc=0 0 0"

mem_test.asm

A simple test of the hdd_driver library. See description at the top of the file.

Issues and nuances

The SYNC instruction (and how it affects CALL and RET)

Command Block Assembly is designed to produce fast and efficient functions, avoiding expensive operations wherever possible.
As such, some features are optimized unless it is not possible.

By default, a CALL instruction will add a /function command to run the subroutine.
This means that once the function finishes, execution continues at the next command.
This behaviour is the anticipated use of CALL, however the implication is that RET has no effect.

Originally, there was going to be an implied return after a subroutine. i.e. always return to caller if CALL is ran.
But the RET instruction is required for SYNC to work, so it was added.

As stated in the instruction description, SYNC effectively "pauses" the current execution until one tick later.

The current calling stack (nested /function calls) will always return to the caller and continue on the next line.
SYNC must nullify the next call so the calling stack returns and the game runs a tick.
However, this is not possible with CALL's guarantee to return to caller.

Therefore, CALL must push the address of the next instruction onto the stack, letting RET pop it off later.
With that, it is now possible to cause an interrupt between CALL and the subsequent RET.
This is how you would expect CALL and RET to function, but doing so is less efficient for the common use-case.

By default, SYNC is disabled. The use of RET prints a warning to stderr saying how it doesn't have any effect. If the program is anticipated to use SYNC, you should defensively use RET anyway. Just keep in mind how the optimization works.

To use SYNC, enable it with --enable-sync.

CMP and jumping

Due to there being no concept of a "status" register, jump instructions don't check flags of any sort.
Instead, they evaluate the most recent CMP instruction.

The assembler keeps a reference to the most recent CMP instruction. If a conditional jump instruction is encountered, it fetches this CMP to decide whether to jump or not.

A more accurate conditional jump could be an instruction that takes 3 arguments e.g: JL left, right, label. However writing out the comparison is clunky when performing a succinct multi-jump like this:

CMP left, right

JE is_equal

JL is_less

JG is_greater

Signed bitwise operations

The bitwise operations (e.g. AND, SHR, ROL) have not been tested for correct handling of negative values. Use with caution.

Quote from SellswordMike»

Also your demonstration of Sponge Plugins in action are pretty much just proof of concept work from what it looks like, I only see "you can do something like this" but not "look, here you see in action what somebody did using our api". As in, it doesnt look like Sponge Plugin coders did that, it looks more like you guys did that as a proof of concept for possibilities. There is nothing wrong with it, just dont label it the way you did.

None of the above plugins are made by the spongepowered project, they are independent developers

Each plugin has a post on the sponge forums, you can find all plugins on the Plugins subforum

https://forums.spongepowered.org/c/plugins

Edifice by Zirconium:

https://forums.spongepowered.org/t/house-edifice-create-and-share-structures-api-5-0-0/12465

ChatUI by simon816 (me):

https://forums.spongepowered.org/t/chat-ui-a-ui-toolkit-for-the-vanilla-chat-box/10109

(admittedly this plugin is not fully released yet but it will be soon(tm))

(yes I am part of the sponge developer team but I make independent stuff too)

Project Portals by TrenTech:

https://forums.spongepowered.org/t/project-portals-v0-13-4/10438

Quote from Mr_TJP»

Will update as soon as CB updates ForgeMultipart.

Mar 01 17:09:39 <amadornes> simon816, the "official" alternative is now MCMultiPart
Mar 01 17:09:51 <amadornes> quoting one of CB's PMs: "unfortunately I don't have time to maintain FMP anymore
Mar 01 17:09:51 <amadornes> "
Mar 01 17:10:18 <amadornes> (dammit, line breaks >_>)
Mar 01 17:11:11 <amadornes> it's supposed to get merged into Forge fairly soon
Mar 01 17:11:18 <amadornes> not sure if on 1.8 or 1.9, though
Mar 01 17:11:24 <amadornes> probably 1.9 since it's right around the corner
Mar 01 17:12:50 <amadornes> it doesn't have some of the features FMP had such as scala traits because it's written in java
Mar 01 17:13:22 <amadornes> but if MC/Forge ever switches to java 8, defaulting interfaces should be fairly easy to add

Quote from alex70414»

why I can't find the wiki of projectred?

Are there any Recipes & Resources for projectred?

The wiki is http://projectredwiki.com/wiki/Main_Page

Quote from kluckart»

I got a crash report. here is the report:

--snip--

That crash is clearly indicating BiblioCraft, there's no reference to Project Red anywhere

Quote from SabejiThePirate»

Can't seem to get mechanical working, keep getting an error

Is it because I need a older forge?

You haven't provided any crash information. However, it looks like you are trying to use the 'Mechanical' module, but don't have 'Integration', you must have Integration in order to use Mechanical.

Minecraft (1.8.3)
|
|--> MCP (1.8)
     |--> Forge Mod Loader (1.8)
          |
          |--> Minecraft Forge (1.8)
               |
               |--> CodeChickenLib (1.8)
                    |
                    |--> Forge Multipart (1.7.10) |
                    |                             |
                    |--> MrTJPCore (1.7.10)       |
                                |                 v
                                |-----> ProjectRed (1.7.10)

Quote from Eunomiac»

I'm having trouble accessing the wiki as well---perhaps it's an intermittent load issue, I'll try again later.

Quote from IHaTeD2»

Well, I have this for months now.

Quote from IHaTeD2»

Bump?!

Tried several PCs, even my damn smartphone via mobile connection and I can't reach the site at all ...

Quote from drew12123»

is there a way to change item ids

Quote from Medraidas»

This is the error report.. Now with this one i am uncertain if it is projectred itself causing errors or something else, as i stated nothing in the pack itself changed other than updating mods to a newer version.

http://paste.ee/p/Dzbfo

If it's not Project Red causing it please let me know what is so i can find the right forums.

Quote from Medraidas»

So, i'm having this issue.. Really getting annoyed lately when trying to make things work.

http://paste.ee/p/a5cw2

Quote from realflow100»

Ur mod does not work with netherores. Crash with no other mods installed but netherores and the corefh Try it urself with latest and see. crash every time. netherores is not useable till this crash is fixed.

---- Minecraft Crash Report ----
// You're mean.

Time: 12/12/14 4:03 PM
Description: There was a severe problem during mod loading that has caused the game to fail

cpw.mods.fml.common.LoaderException: java.lang.NoSuchMethodError: net.minecraft.util.ChatStyle.setColor(Lnet/minecraft/util/EnumChatFormatting;)Lnet/minecraft/util/ChatStyle;
at cpw.mods.fml.common.LoadController.transition(LoadController.java:162)
at cpw.mods.fml.common.Loader.preinitializeMods(Loader.java:515)
at cpw.mods.fml.client.FMLClientHandler.beginMinecraftLoading(FMLClientHandler.java:239)
at net.minecraft.client.Minecraft.func_71384_a(Minecraft.java:480)
at net.minecraft.client.Minecraft.func_99999_d(Minecraft.java:867)
at net.minecraft.client.main.Main.main(SourceFile:148)
at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
at sun.reflect.NativeMethodAccessorImpl.invoke(Unknown Source)
at sun.reflect.DelegatingMethodAccessorImpl.invoke(Unknown Source)
at java.lang.reflect.Method.invoke(Unknown Source)
at net.minecraft.launchwrapper.Launch.launch(Launch.java:135)
at net.minecraft.launchwrapper.Launch.main(Launch.java:28)
Caused by: java.lang.NoSuchMethodError: net.minecraft.util.ChatStyle.setColor(Lnet/minecraft/util/EnumChatFormatting;)Lnet/minecraft/util/ChatStyle;
at cofh.mod.updater.UpdateManager.<clinit>(UpdateManager.java:28)
at cofh.CoFHCore.preInit(CoFHCore.java:92)
at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
at sun.reflect.NativeMethodAccessorImpl.invoke(Unknown Source)
at sun.reflect.DelegatingMethodAccessorImpl.invoke(Unknown Source)
at java.lang.reflect.Method.invoke(Unknown Source)
at cpw.mods.fml.common.FMLModContainer.handleModStateEvent(FMLModContainer.java:513)
at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
at sun.reflect.NativeMethodAccessorImpl.invoke(Unknown Source)
at sun.reflect.DelegatingMethodAccessorImpl.invoke(Unknown Source)
at java.lang.reflect.Method.invoke(Unknown Source)
at com.google.common.eventbus.EventSubscriber.handleEvent(EventSubscriber.java:74)
at com.google.common.eventbus.SynchronizedEventSubscriber.handleEvent(SynchronizedEventSubscriber.java:47)
at com.google.common.eventbus.EventBus.dispatch(EventBus.java:322)
at com.google.common.eventbus.EventBus.dispatchQueuedEvents(EventBus.java:304)
at com.google.common.eventbus.EventBus.post(EventBus.java:275)
at cpw.mods.fml.common.LoadController.sendEventToModContainer(LoadController.java:208)
at cpw.mods.fml.common.LoadController.propogateStateMessage(LoadController.java:187)
at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
at sun.reflect.NativeMethodAccessorImpl.invoke(Unknown Source)
at sun.reflect.DelegatingMethodAccessorImpl.invoke(Unknown Source)
at java.lang.reflect.Method.invoke(Unknown Source)
at com.google.common.eventbus.EventSubscriber.handleEvent(EventSubscriber.java:74)
at com.google.common.eventbus.SynchronizedEventSubscriber.handleEvent(SynchronizedEventSubscriber.java:47)
at com.google.common.eventbus.EventBus.dispatch(EventBus.java:322)
at com.google.common.eventbus.EventBus.dispatchQueuedEvents(EventBus.java:304)
at com.google.common.eventbus.EventBus.post(EventBus.java:275)
at cpw.mods.fml.common.LoadController.distributeStateMessage(LoadController.java:118)
at cpw.mods.fml.common.Loader.preinitializeMods(Loader.java:513)
... 10 more


A detailed walkthrough of the error, its code path and all known details is as follows:
---------------------------------------------------------------------------------------

-- System Details --
Details:
Minecraft Version: 1.7.10
Operating System: Windows 7 (amd64) version 6.1
Java Version: 1.8.0_25, Oracle Corporation
Java VM Version: Java HotSpot(TM) 64-Bit Server VM (mixed mode), Oracle Corporation
Memory: 853810552 bytes (814 MB) / 1060372480 bytes (1011 MB) up to 1060372480 bytes (1011 MB)
JVM Flags: 13 total; -XX:HeapDumpPath=MojangTricksIntelDriversForPerformance_javaw.exe_minecraft.exe.heapdump -Xms1024M -Xmx1024M -XX:+CMSIncrementalMode -XX:-UseAdaptiveSizePolicy -XX:UseSSE=4 -XX:+UseConcMarkSweepGC -XX:+UseCMSCompactAtFullCollection -XX:+UseParNewGC -XX:+DisableExplicitGC -XX:+AggressiveOpts -Xrs -Xmn128M
AABB Pool Size: 0 (0 bytes; 0 MB) allocated, 0 (0 bytes; 0 MB) used
IntCache: cache: 0, tcache: 0, allocated: 0, tallocated: 0
FML: MCP v9.05 FML v7.10.85.1236 Minecraft Forge 10.13.2.1236 6 mods loaded, 6 mods active
mcp{9.05} [Minecraft Coder Pack] (minecraft.jar) Unloaded->Constructed->Pre-initialized
FML{7.10.85.1236} [Forge Mod Loader] (forge-1.7.10-10.13.2.1236.jar) Unloaded->Constructed->Pre-initialized
Forge{10.13.2.1236} [Minecraft Forge] (forge-1.7.10-10.13.2.1236.jar) Unloaded->Constructed->Pre-initialized
<CoFH ASM>{000} [CoFH ASM Data Initialization] (minecraft.jar) Unloaded->Constructed->Pre-initialized
CoFHCore{1.7.10R3.0.0B8} [CoFH Core] (CoFHCore-3.0.0B8-dev.jar) Unloaded->Constructed->Errored
NetherOres{1.7.10R2.3.0RC3} [Nether Ores] (NetherOres-[1.7.10]2.3.0RC3-84.jar) Unloaded->Constructed->Errored

Quote from Skia»

Are there any plans to ever include frames? I miss being able to make frameships. If the engines could be made a little more compact too, that'd be great

Truly though, nice mod. I do hope that frames don't get forgotten however.

Quote from Mr_TJP»

Quote from Mr_TJP»

Every time I sit down to get some modding done, college gets in the way >:(

What I'm doing now:

Frames API:
Working, needs cleaning/textures before release. API implementation works good.

ProjectRed:
Refining the documentation on the wiki, working on bugs mostly..

To the patrons: Thanks, guys. And don't worry, I'm not forgetting about the rewards!

Quote from ShichiNoBushi»

I checked the OP, and though it does have 4.5.5 in the title, I can't find any links other than to the ones I used to get the older (apparently bugged) versions. I do see the link to Patreon. If that's the only way to get the file, I apologize that I can't afford to pay for something like that. If it is somewhere in that post, it's not at all clear enough.

Edit: Never mind. I found it in the Version Archive. I suppose all the red threw me off, and I didn't properly check the version numbers of the most recent.

Edit-2: Now I have the proper 4.5.5.56 files, but I'm getting a different error.


It seems to not be able to find ForgeMultipart. But I've been noticing that every time since I added ProjectRed that the Multipart .jar file keeps disappearing from my mods folder and being placed int a "1.7.10" folder within it. Why is it doing this? Is it creating its own problems? Is there something else I'm missing, now?