Hanmin's Minecraft Math Module
This library was originally written because of the fact that Minecraft can only perform arithmetic operations on 32-bit signed integers, which is insufficient for many practices. This library can compactly store 32-bit floating point numbers as integers, in addition to being able to perform operations on them. In the future, I hope that this library will be able to store 64-bit objects as two integers.
Another useful function of this library is that it lets you easily create lists and perform operations on them (hopefully anyways, as I haven't actually made that at the time of writing).
If you want to make it a submodule of your pack, please read the LICENSE first, then add the "pack-module" branch as a submodule with the directory name "hmmm":
git submodule add -b pack-module https://github.com/LovelyZeeiam/Hmmm-Pack-Module.git data/hmmm/
Unfortunately, there is no style standard for Minecraft Functions. Thus, I will briefly describe the style standard I will be using.
Function Header All functions will have a header comprised of four sections:
- path
The name will be in datapack:folder/subfolder/file format. This is identical to how functions are called in Minecraft. - description
A simple description of the function - parameters
The variables that will be used as inputs for the function. - return variables
The variables the outputs will be assigned to.
Variables
Minecraft essentially has two main methods of holding data: scoreboards and data storage. Scoreboards can only hold signed 32 bit integers, while data storage can hold virtually any variable type (int, float, double, string, lists, etc).
Scoreboard Variables
Variables which hold data in the form of scoreboards will be represented in the format:
O.Pn
In which O is the scoreboard objective name, P is the prefix for the scoreboard player name (optional), and n is an index.
For example, the variable hmmm_io.R0 could be accessed in-game using /scoreboard players get R0 hmmm_io
.
Multiple variables can be represented using square brackets. For example:
hmmm_io.R[0..3]
would represent variables hmmm_io.R0, hmmm_io.R1, hmmm_io.R2, hmmm_io.R3
hmmm_io.R[0, 2, 6]
would represent variables hmmm_io.R0, hmmm_io.R2, hmmm_io.R6
Storage Variables
Variables which hold data in the form of data storage will be represented in the format:
{O.P}
In which O is the target name, and P is the target path.
For example, the variable {io.R0} can be accessed in-game using /data get storage hmmm:io R0
(Note: All data storage used in this datapack have prefix 'hmmm'.
Storage variables can also be indexed using curly brackets. For example:
{io.R0}[5]
would represent the 6th element in {io.R0} (because arrays begin at 0).
Hmmm features:
signed and unsigned 32-bit:
- Addition
- Subtraction
- Multiplication
- Division
- Modulo
- Bitwise AND
- Bitwise shift left/right
- Create list of bits using 32-bit integer
32-bit floating-point (basic):
- Decomposition (32-bit decomposition into to 1-bit, 8-bit, and 23-bit chunks)
- Recomposition (inverse of Decomposition)
- Addition
- Subtraction
- Multiplication
- Division
- Conversion to Storage (convert 32-bit representation into Minecraft NBT Storage format)
- Conversion to Storage as Double (convert 32-bit representation into Minecraft NBT Storage format)
- Conversion from int (convert Minecraft scoreboard to 32-bit representation)
- Negation (x -> -x, -x -> x)
- Absolute Value
- Compare (less, less or equal, equal, greater or equal, greater)
32-bit floating-point (extended):
- Floor
- Ceiling
- Truncate (round to 0)
- Log
- Exponent (e^)
- Power
- nth Root
- Inverse Square Root
- Sine
- Cosine
- Tangent
- Arcsine
- Arcosine
- Arctangent
All Bitwise Functions:
Signed (most of them are exactly the same as Minecraft scoreboard operations):
hmmm:bitwise/32/signed/add/main
hmmm:bitwise/32/signed/and/main
hmmm:bitwise/32/signed/divide/main
hmmm:bitwise/32/signed/modulo/main
hmmm:bitwise/32/signed/multiply/main
hmmm:bitwise/32/signed/shift/left/main
hmmm:bitwise/32/signed/shift/right/main
hmmm:bitwise/32/signed/subtract/main
hmmm:bitwise/32/signed/to_bits/main
Unsigned:
hmmm:bitwise/32/unsigned/add/main
hmmm:bitwise/32/unsigned/and/main
hmmm:bitwise/32/unsigned/divide/main
hmmm:bitwise/32/unsigned/modulo/main
hmmm:bitwise/32/unsigned/multiply/main
hmmm:bitwise/32/unsigned/shift/left/main
hmmm:bitwise/32/unsigned/shift/right/main
hmmm:bitwise/32/unsigned/subtract/main
hmmm:bitwise/32/unsigned/to_bits/main
Detailed information about each of these functions can be found by opening the datapack and opening each function file.
Although it is possible to perform unsigned 32-bit integer arithmetic, the parameters and the result will still be a Minecraft scoreboard value, or a signed 32-bit integer. Thus, it is not possible to directly use this output. Pretend that there is a leading '1' bit if the scoreboard value is negative. You could also use the hmmm:bitwise/32/signed/to_bits/main
function to create a 32-bit little endian boolean array hmmm_io.R[0..31].
Functions that take in two parameters will take:
hmmm_io.P[0, 1] as inputs and hmmm_io.R0, hmmm_io.R1 (if applicable) as output.
Example Usage
To perform 1+1
:
scoreboard players set P0 hmmm_io 1
scoreboard players set P1 hmmm_io 1
function hmmm:bitwise/32/signed/add/main
Then, the result can be returned using:
scoreboard players get R0 hmmm_io
All Floating-Point Functions:
hmmm:float/32/decompose/main
hmmm:float/32/recompose/main
hmmm:float/32/add/main
hmmm:float/32/subtract/main
hmmm:float/32/multiply/main
hmmm:float/32/divide/main
hmmm:float/32/convert/to_storage/main
hmmm:float/32/convert/to_storage_double/main
hmmm:float/32/convert/from_int/main
hmmm:float/32/negate/main
hmmm:float/32/absolute_value/main
hmmm:float/32/compare/less
hmmm:float/32/compare/less_equal
hmmm:float/32/compare/equal
hmmm:float/32/compare/greater
hmmm:float/32/compare/greater_equal
hmmm:extended_float/32/floor
hmmm:extended_float/32/ceiling
hmmm:extended_float/32/truncate
hmmm:extended_float/32/log
hmmm:extended_float/32/exponential
hmmm:extended_float/32/power
hmmm:extended_float/32/root
hmmm:extended_float/32/fast_inverse_sqrt
hmmm:extended_float/32/sin
hmmm:extended_float/32/cos
hmmm:extended_float/32/tan
hmmm:extended_float/32/asin
hmmm:extended_float/32/acos
hmmm:extended_float/32/atan
Detailed information about each of these functions can be found by opening the datapack and opening each function file.
Similar to unsigned 32-bit integers, floating point numbers in this datapack will still be represented as signed 32-bit integers because that's the only thing Minecraft scoreboards can handle. Although NBT Storage is able to store floating-point numbers, there is no way to perform any meaningful operations with them (at least, none that are practicle). I chose to represent floating-point numbers with scoreboard values because both take up 32 bits, and storing floating-point values as scoreboards means that it can be easily stored for later use (in an NBT storage array or possibly on an entity).
For instance, the floating point number '86.5', which has a binary representation of '01000010101011010000000000000000' will be stored as a scoreboard value of '1118633984'. We will call these integer values 'raw floats'.
Before performing any operations on our raw floats, we must decompose them.
The hmmm:float/32/decompose/main
function takes a raw float and returns three scoreboard values hmmm_io.R[0..2]: sign, exponent, and significand (mantissa). You don't need to know what these are to use the library. You can use hmmm:float/32/recompose/main
to turn these three values back into a raw float.
To perform operations on floats, you should set hmmm_io.P[0..2] and hmmm_io.P[3..5] each to the returned values of a decomposed float.
Example Usage
To perform 27504.27734375 + 64317.64453125 = 91821.921875
:
# 1188487310 is the integer representation of 64317.64453125 (both 01000110110101101110000010001110)
scoreboard players set P0 hmmm_io 1188487310
function hmmm:float/32/decompose/main
# copy hmmm_io.R[0..2] to hmmm_io.P[3..5].
scoreboard players operation P3 hmmm_io = R0 hmmm_io
scoreboard players operation P4 hmmm_io = R1 hmmm_io
scoreboard players operation P5 hmmm_io = R2 hmmm_io
# 1199259045 is the integer representation of 27504.27734375 (both 01000111011110110011110110100101)
scoreboard players set P0 hmmm_io 1199259045
function hmmm:float/32/decompose/main
# copy hmmm_io.R[0..2] to hmmm_io.P[0..2].
scoreboard players operation P0 hmmm_io = R0 hmmm_io
scoreboard players operation P1 hmmm_io = R1 hmmm_io
scoreboard players operation P2 hmmm_io = R2 hmmm_io
# finally call the function to add hmmm_io.P[0..2] and hmmm_io.P[3..5]
function hmmm:float/32/add/main
# if you're done, you can turn these values back into a raw float.
# set the result to the parameter
scoreboard players operation P0 hmmm_io = R0 hmmm_io
scoreboard players operation P1 hmmm_io = R1 hmmm_io
scoreboard players operation P2 hmmm_io = R2 hmmm_io
# turn the three scoreboard variables back into one raw float.
function hmmm:float/32/recompose/main
You can get the result of this using:
scoreboard players get hmmm_io R0
which will return 1202935542, or 01000111101100110101011011110110 in binary and 91821.921875 as a floating point representation.
You can also convert floating point numbers into NBT Storage using hmmm:float/32/convert/to_storage/main
if you want to use it to modify say, an armor stand pose or whatever you might need super accurate floating-point NBTs for.
Example Usage
To turn 1199259045 (01000111011110110011110110100101) to 27504.27734375:
# first decompose the raw float
scoreboard players set P0 hmmm_io 1199259045
function hmmm:float/32/decompose/main
# copy results to input
scoreboard players operation P0 hmmm_io = R0 hmmm_io
scoreboard players operation P1 hmmm_io = R1 hmmm_io
scoreboard players operation P2 hmmm_io = R2 hmmm_io
# convert to NBT storage. Return to {io.R0}
function hmmm:float/32/convert/to_storage/main
You can access the returned NBT storage float using
data get storage hmmm_io hmmm:R0
Hopefully that wasn't too confusing, it's my first time writing a lengthy documentation and I hope you understood everything! Please don't hesitate to contact me if there's anything that you think is unclear.
This library is protected under the MIT standard license. In essense:
- You can do whatever you want with this as long as you provide credit (Must contain name "hanmangokiwi")
- It's not my fault if my code doesn't work and broke something. I'm not responsible if you decided it would be funny to launch a nuclear missile with my code and an error causes it to destroy your home (but why are you using Minecraft for this?).
- Read the included LICENSE file for detailed information