Community:Computer Manual

WarGroove Computer Map
Operation Manual

Currently a Work In Progress!

Author: Emo Tarquin

Last revision: 23rd November 2020

Introduction

This manual provides information and background on the WarGroove Computer Map developed by myself. It provides detailed info on how to operate it, and provides contextual information to understand what is being shown. It helps immensely if you have any form of programming background to understand this, as for all intents and purposes this is like a gamified Assembly code. I write this manual simply, and provide all the information within this document, but for concision I assume you understand these concepts without additional explanation.

What does it do?

This construction is a Turing Complete computer built entirely in Vanilla WarGroove. You can code instructions to perform complex mathematical tasks, make simplistic games, and colourful animations. While simple in scope and plainly impractical for any serious task, the main purpose is to enable the theoretical capacity of making software within WarGroove on a computer machine.

How do I use it?

Put briefly, you move wagons around and type in numbers into various positions. These numbers represent the instructions you want it to perform. When you hit the Start button, it will begin the program, and can output data as a number or on a graphical display. I’ll explain in more detail how each component works further on.

Why did you make this?

Got bored. ¯\_(ツ)_/¯

Meet The Machine

Below is a full-map view of the entire WarGroove computer

(Missing images will have placeholder turtles for now, sorry!)

There’s a lot to look at here, so I’ll break it into parts.

Memory Stack

This is where your software is programmed. You can imagine it like one long piece of tape, where every time you reach the bottom it’s instantly joined to the top of the next column (those Alchemists mark the joins!). For now, it’s empty. When instructions are written onto it, they’ll look like 2 wagons, the left one will be an Instruction, and the right one is a Parameter (more on that later). When the computer is running, it goes row-by-row, and every single row represents one instruction you want it to do (or in the case of empty spaces, do nothing). When we want to edit this, we need to come over to…

Stack Editor

...the stack editor! It looks messy, but it’s super simple. The wagon on the far-left side of the stack is a row selector, whatever row it’s on is the row we want to edit. The wagon slider in our editor section selects the column. Whatever space we have selected will appear highlighted on the stack!

Control Buttons

Top one is the Start button, which starts the program. Middle one is the Continue button which we can press if we paused our program. Bottom one is the ‘Halt and Catch Fire’ button--ends the program manually. We also have a fourth one for the Operation Mode, this basically means if we’d like our computer to only move forward every time we say to do so, or if it should run automatically and as fast as it can go.

Step Button and Loop Villager

Remember I mentioned how the Operation Mode lets you make the computer go forward only when we say so, and how the Villagers waiting was a type of button? Well, that’s what the Merfolk is. The Merfolk button is active during “Step” Operation Mode, during which the computer will only ever perform 1 instruction at a time when we click Wait with the Merfolk. You basically gotta button mash to get it moving fast, but it lets you precisely monitor your program in some ways. The Villager on the other hand is the “run loop” mechanism used during “Autonomous” Operation Mode. You can’t touch him, but they’re integral to how the computer can run automatically at (mildly) breakneck speeds!

Rounding Wagon

Similar to the Loop Villager, you cannot touch this. This Wagon is basically used for handling the “rounding” operations used throughout many of the programming instructions. You can actually see the last performed rounding operation in its health.

Error Light

This empty box is actually a light, sorta! If something goes wrong, this will flash with a colour to tell you the general reason for it, to let you fix any mistakes in your code. Trust me, with how restrained coding is in this map, you’ll be very glad I gave you this.

Print Display

Our programs will predominantly do number jobs, this here is how you’ll see what numbers are coming out! Each Wagon’s health represents 2 digits of the full number, with the lava pool as a ‘decimal point’.

The Ninkoji GrooveBoy

Eh? Ehhhh? ... Fine.

This castle-sized handheld games console is a big part of interacting with the computer. Those buttons can provide input data during operation of the program. Of course they do nothing if the program isn’t coded to respond to those inputs.

There’s also a 6x6 graphical display, with 10 colour settings per pixel, which can be used to make the most flashy of outputs... given enough effort. It’s still controlled with numbers on the inside, but this lets us achieve some more appealing results that are more appealing (people just can’t appreciate some solid fundamental maths! Such a shame.)

And that’s everything on the outside. Next, I want to explain a bit about how it works on the ‘inside’. This is where our programming instructions will play a big part!

Understanding the Mechanics

So this is where it gets technical. I’ll begin with the most important concepts first, ones that are important to understanding how we can use this machine.

Data Registers

Registers are a kind of data storage. We can use them like variables in any programming language you might be familiar with. Only real difference is we can’t define variables, they’re pre-defined and built-in!

Registers are simple, really. They hold a single number, which can even be negative and can have decimal values. Only real limitation is we can’t do fractional values (i.e. you can’t do a true ⅓, but you can get pretty close!).

Line Feed

The Memory Stack is made up of many rows, each row can hold one Instruction and one Parameter. Not all instructions require a Parameter value, but every Instruction type has a unique Instruction number to identify it.

When the computer is running, it will read the first row, perform that instruction, and go onto the second row, perform that, and go onto the third. It always moves in a perfectly linear fashion. We can do some more interesting stuff using “JUMP” statements, where we relocate the reader’s position to somewhere else using an instruction, letting us do loops, and ‘branching’ if we set a conditional for the jump, but the reader itself will always move forwards linearly.

Loss of Player Control

Due to a limitation of WarGroove, you will be unable to control anything while the program is running (in Autonomous mode). You can move your screen around but your cursor will be invisible and can select nothing.

As a result, you can’t move units to edit those input buttons either. Instead, you will need to set an instruction to pause (or ‘BREAK’) the program to return control to the player, who must then press the Continue button to keep going.

For safety reasons I set a hard limit on how long the program will run before it ends the program itself, but if you remove the limiter this can actually softlock your game and force a hard restart, so I don’t recommend it.

Stored Data

We’re storing numbers, simple really, but there are some quirks you need to watch out for, like if a number gets too massive (or too far into the negatives) it can “wrap around” and end up on the opposite end. Registers are not infinite, so be wary of that.

Technical Specifications

Computer specifications

Running speed	Approximately 16 cycles per second
Stack size	846 instructions
Accumulators	6
Accumulator size	64-bits
Available registers	16
Register size	64-bits
Operational limit	-1010 ~ 1010 (Approx. 34-bits)

Map information

Download code	To be announced
Map Size: 58x96
Players	1

Registers

Available Registers

Some instructions accept a register as an input. The reference values indicate what numerical input refers to what registers. Referencing a non-existent register will result in an error. There are a total of 16 registers, 15 are addressable.

Type	Reference values	Datatype
Active	9	64-bit Floating Point
Storage	1 ~ 8	64-bit Floating Point
Print	10	64-bit Floating Point
Display	11 ~ 16	64-bit Floating Point

64-bit Floating Point Datatype

All registers store values in double-precision floating points.

A useful quirk of these is they can store integer values at perfect precision, allowing integer calculations to operate as expected.

During some functions, a non-integer value may be stored to a register. As this uses a floating-point value its precision is limited. This can cause some values to erroneously be marginally larger or smaller than anticipated (resulting in floating-point rounding errors).

Due to limitations, many of the functions will introduce additional imprecision for floating-point values, and none of the outputs are able to accurately display the true value of a lengthy floating-point value.

It is strongly advised to take caution when handling floating point values due to unpredictable behaviours.

Operational Range

Registers store a double-precision floating point, this means they can store all integers from -10^53 to +10^53 without loss of precision, and go to a maximum of ≈1.8x10308. However, many functions are limited to a smaller range.

Any instruction based upon a rounding operation internally can only handle values such that the processed value is between -10^10 and +10^10. This is a safeguard against integer values that cannot be processed correctly due to the imprecise method by which integer values are displayed and rounded. However, this will not protect against errors resulting from high-precision floats.

Details of this limitation can be found on the instruction details. Performing an instruction with a value outside of its operational range will result in an error.

Display Register References

Each Display register corresponds to one column of the graphical display, and each digit corresponds to a pixel along the column.

While unadvisable, the Display registers can tolerate floating-point values and values that exceed 6 digits. In such instances, only the first 6 digits above the decimal point will be considered.

If the Display Register’s value exceeds 100,999,999, it will always result in a graphical output identical to 999,999.

Labels and Initialisation

Jump labels are required for performing long jump instructions across the stack (see LABEL JUMP). Labels are defined by setting Instruction 37 (LABEL) commands, with the label number as the Parameter. Labels are visibly identified as Dogs on the map, instead of Wagons.

Before the program runs, an initialisation phase is run, where labels are identified and converted into a usable state. Having more than one of the same label, or an invalid label reference, will result in an error.

The initialisation phase will take 1 cycle per LABEL instruction in the stack, taking zero cycles if no LABEL instructions are present. This is not subject to the cycles limiter and does not go to its count, as it will always terminate after processing each LABEL once.

There are a total of 8 labels.

Type	Reference Values
1 ~ 8

Input and Output

Input

Inputs are made by moving the provided units within the Ninkoji GrooveBoy onto the designated pressure plates, acting as physical buttons. There are 4 buttons, and a 4-directional pad.

Due to the nature of WarGroove, units cannot be moved during software operation, therefore the input can only be modified when the software has been halted, or paused using the BREAK instruction.

Print Output

A numerical value can be output to the health values of a line of wagons situated above the Ninkoji GrooveBoy. Each wagon’s health provides a 2-digit display of the total value. The lava spot indicates the decimal point, and can display a maximum of 10 digits above the decimal point, and 4 digits below the decimal point.

The print output can only display one value at a time, any new value will immediately fully override the previous value.

Graphical Output

On the Ninkoji GrooveBoy is a 6x6 graphical display. Each pixel is referred to by a digit in a Display register (see Display Register References).

Each pixel can independently be coloured and illuminated one of 10 different settings:

Value	Colour
0	Red
1	Blue
2	Green
3	Yellow
4	Purple
5	Teal
6	Pink
7	Orange
8	Dim grey
9	Bright grey

Error Codes

When the program terminates, it produces a flashing indicator. This chart identifies error lights with the type of error encountered.

Code number	Colour	Cause of error
1	None	Terminated by program
2	None	Terminated by user (HCF button)
3	Grey	Cycles limit reached
4	Red	Invalid instruction
5	Orange	Invalid parameter
6	Yellow	Number out of operational range
7	Blue	More than one copy of the same jump label
8	Teal	Invalid jump label specified
9	Black	End of stack reached

Instructions 1 ~ 2: Basic Control

These functions provide the simplest, most basic control of the computer.

Instructions with no input values will be read as NULL.

NULL - No instruction

This instruction will perform no action.

1 - No instruction

This instruction will perform no action.

2 - SET

The value in the Parameter is copied to the Active register.

Instructions 3 ~ 20: Arithmetic Functions and Math

These instructions provide the core arithmetic functions of the computer, acting upon the Active Register to perform a wide variety of calculations, along with high-precision common mathematical constants.

3 - ADD

Adds the Parameter to the Active Register’s current value (A+P).

4 - SUBTRACT

Subtracts the Parameter from the Active Register’s current value (A-P).

5 - MULTIPLY

Multiplies the Active Register’s value by the value in the Parameter (A×P).

6 - DIVIDE

Divides the Active Register’s value by the value in the Parameter (A÷P).

Warning: this will produce floating-point values if the division does not create an integer result.

7 - EXPONENT

The Active Register is raised by the Parameter as an exponent (AP).

Values 1 ~ 50 are mapped as 1 ~ 50, while values 51 ~ 100 are mapped as -1 ~ -50. This allows root calculation.

Examples:

 SET 16
 EXPONENT 52    -- Performs a ‘Square Root’. Result is  4

 SET 2
 EXPONENT 3     -- Performs a ‘Cubed’. Result is 8

Note: this function takes ⌈ P÷8 ⌉ cycles to complete, at a maximum of 13 cycles when Parameter ≥ 96

8 - REMAINDER

Performs a division (see DIVIDE) of form A÷P, and stores the integer remainder to the Active Register. Output will match the sign of the dividend.

Examples:

 SET 17
 REMAINDER 4    -- Result is 1.	

 SET 23
 NEGATE
 REMAINDER 3    -- Result is 2.

Note: This can only handle division outputs between -101 and 101, not inclusive (e.g. 403 Remainder 4 is acceptable, but 404 Remainder 4 is not). Outside the operational range will result in erroneous outputs.

9 - MODULO

Performs a modular operation on the Active register (A MOD P) to create an integer within the bounds between 0 and the Parameter value, inclusively.

Examples:

 SET 17
 REMAINDER 4    -- Result is 1.	

 SET 23
 NEGATE
 REMAINDER 3    -- Result is 1. Note the difference from the Remainder function when the dividend is negative.

Note: This can only handle division outputs between -101 and 101, not inclusive (e.g. 403 MOD 4 is acceptable, but 404 MOD 4 is not). Outside the operational range will result in erroneous outputs.

10 - ROUND

Rounds the Active Register to the nearest Integer value. Floating values will be converted into Integer type. Half roundup is applied.

Examples:

 5.5 ⇒ 6
-3.5 ⇒ -4

Note: This can only handle values between 0 and 101, excluding 101. Values exceeding this range will result in outputs equivalent to 0 or 100, respectively.

11 - CEILING

Rounds the Active Register up to the nearest Integer value. Floating values will be converted into Integer type. Rounding up goes to the value furthest from zero.

Examples:

 5.1 ⇒ 6
-3.2 ⇒ 4

12 - FLOOR

Rounds the Active Register down to the nearest Integer value. Floating values will be converted into Integer type. Rounding downs goes to the value closest to zero.

Examples:

 5.7 ⇒ 5
-3.8 ⇒ 3

13 - ABSOLUTE

Returns the absolute value of the Active Register (|A|), converting any negative value to a positive value, and leaving positive values unchanged.

14 - NEGATE

Returns the negated value of the Active Register (-A), converting any negative value to a positive value, and any positive value to a negative value.

15 - RANDOM

Stores a random floating-point value to the Active Register. This value can be any amount between 0 and 1, excluding 1, and is precise to 6 decimal places.

16 - Pi

Stores the value Pi to the Active Register, precise to 6 decimal places (3.141593).

17 - NATURAL

Stores the natural exponent e to the Active Register, precise to 6 decimal places (2.718282).

18 - TRIGONOMETRY

Returns the result of a trigonometric function applied on the Active register.

A function is chosen by the greater digit of the Parameter.

Input value	Selected function
11 ~ 12	Sine
21 ~ 22	Cosine
31 ~ 32	Tangent
41 ~ 42	Cosecant
51 ~ 52	Secant
61 ~ 62	Cotangent

The smaller digit determines if the value is given as Radians or Degrees.

Input value	Unit of angle
1	Degrees
2	Radians

Examples:

 SET 90
 TRIG 11      -- Performs Sine with Active register degrees. Returns 1.

 PI
 TRIG 32      -- Performs Tangent with Active register radians. Returns 0.

Note: calculations are performed using the first 4 elements of the Taylor series of calculation.

19 - Logarithm

Returns the logarithm of the Active Register with respect to a base of the Parameter (LogP(A)).

A Parameter of 1 will return a logarithm to the base e.

Examples:

 SET 32
 LOG 2        -- Calculates Log2(32). Returns 5.

 SET Natural
 LOG 1        -- Calculates Ln(e). Returns 1.

Note: Calculations are performed using the first 4 elements of the Taylor series of calculation.

Instructions 21 ~ 30: Register Handlers

These instructions provide arithmetic operations using the Active Register as a parameter, and data transfer between registers to manipulate several values and develop an output

Input parameters are register reference values. Please refer to Registers for more information.

21 - REG ADD

Adds the value stored in the Active register to the value in the selected register (R+A).

22 - REG SUBTRACT

Subtracts the value stored in the Active register from the value in the selected register (R-A).

23 - REG MULTIPLY

Multiplies the value stored in the Active register to the value in the selected register (R×A).

24 - REG DIVIDE

Divides the value stored in the Active register from the value in the selected register (R÷A).

25 - REG MODULO

???

26 - REG EXPONENT

The selected register is raised by the Active register as an exponent (RA).

27 - COPY ATS

Copies the value in the Active register, and stores it to the selected register.

28 - COPY STA

Copies the value in the selected register, and stores it to the Active register.

29 - SWAP

Swaps the values in the Active and selected registers.

Instructions 31 ~ 40: Line Jumps

These instructions allow the computer to move the reader position to previous or far-distant positions of the memory stack. These also allow the creation of loops, and conditional branching.

Warning: An offset jump of -1 will always create a non-terminating loop, and operation will not end until the cycles limit is reached.

31 - PARA JUMP

Performs an offset jump based on the Parameter value.

Values 1 ~ 50 are mapped as forward jumps of values 1 ~ 50, while values 51 ~ 100 are mapped as backwards jumps of values 1 ~ 50.

32 - REG JUMP

Performs an offset jump based on the value within the Active register.

33 - Conditional Jump GZ

Performs an offset jump based on the Parameter value (see PARA JUMP), if the Active register’s stored value is greater than zero (>0).

34 - Conditional Jump EZ

Performs an offset jump based on the Parameter value (see PARA JUMP), if the Active register’s stored value is equal to zero (=0).

35 - Conditional Jump LZ

Performs an offset jump based on the Parameter value (see PARA JUMP), if the Active register’s stored value is less than zero (<0).

36 - Conditional Jump NZ

Performs an offset jump based on the Parameter value (see PARA JUMP), if the Active register’s stored value is not zero (≠0).

37 - LABEL

This instruction will perform no action during runtime.

Labels are scanned before runtime operation for the purposes of label jumps.

38 - LABEL JUMP

Jumps directly to the position of the referenced label and continues on the next line.

Instructions 41 ~ 50: Input and Data

These instructions control the input interface for the computer, and miscellaneous data about the current computer operation.

41 - READ A

If a unit is present on the A button, sets Active Register to 1, otherwise no change is made.

42 - READ B

If a unit is present on the B button, sets Active Register to 1, otherwise no change is made.

43 - READ DPAD

Sets the Active register to a value based on which Direction Pad button has a unit present. If no unit is present on any directional button, no change is made.

Direction	Value
Up	1
Down	2
Left	3
Right	4

47 - READ START

If a unit is present on the Start button, sets Active Register to 1, otherwise no change is made.

48 - READ SELECT

If a unit is present on the Select button, sets Active Register to 1, otherwise no change is made.

49 - RUNTIME

The Active register is set to a floating-point value representative of the estimated run-time since starting the program, measured in seconds.

This is calculated on the assumption the computer runs at 16 cycles per second (0.0625 seconds per cycle) and does not account for pauses in operation.

Instructions 51 ~ 60: Graphics

These instructions manipulate data within the Display registers in complex methods for producing unique effects on the display output.

51 - ROTATE CANVAS

Shifts the entire display in one of four directions. Any row/column at the edge is returned on the other side.

Parameter value	Direction
1	Up
2	Down
3	Left
4	Right

Examples:

Assume a series of Display values forming the grid:

4	8	4	8	4	8
4	8	4	8	8	8
4	4	4	8	4	8
4	8	4	8	4	8
4	8	4	8	4	8
4	8	4	8	4	8

 ROTATE CANVAS 1 -- Shifts the image up, resulting in…

4	8	4	8	8	8
4	4	4	8	4	8
4	8	4	8	4	8
4	8	4	8	4	8
4	8	4	8	4	8
4	8	4	8	4	8

 ROTATE CANVAS 3 -- Shifts the image left, resulting in…

8	4	8	4	8	4
8	4	8	8	8	4
4	4	8	4	8	4
8	4	8	4	8	4
8	4	8	4	8	4
8	4	8	4	8	4

59 - UPDATE

Updates the graphical display to the current colour configurations.

Note: colours may flash momentarily while updating. This operation takes much longer to perform, but is still considered 1 cycle.

Instructions 61 ~ 100: Operation Control

These instructions control and manage the configurations and behaviours of the computer’s operation. On startup the software will have values pre-defined, but can be edited using these instructions.

61 - WAIT

The computer will suspend operation for precisely 1 second, before continuing to the next line.

Note: This value is not accounted for in the TIME instruction.

62 - PRINT

Takes the value stored in the Print register, and outputs it to the print display.

63 - OPMODE

Overrides previous Operation Mode settings automatically.

Parameter value	Operation Mode
1	Autonomous
2	Step

64 - CYCLES

Overrides the maximum cycles limit, with 1000 multiplied by the Parameter (1000×P)

A Parameter of 100 removes the safety limit entirely.

This instruction will not reset the current cycles count, and operation will immediately terminate if set below the current value.

Warning: take extreme caution with this setting, as improper use can result in universe-rupturing errors.

Example:

 CYCLES 24       -- Sets the limit to 24,000 cycles.
 CYCLES 100      -- Disables limit

65 - BREAK

Suspends operation and returns control to the input interface.

70 - TERMINATE

Terminates the program.

EOS - End of stack

Instruction called when the end of the memory stack is reached.

Automatically terminates the program.