|
| 1 | +# Minecraft Math |
| 2 | + |
| 3 | +A set of utilities and functions for common math operations. Major pieces are covered below. |
| 4 | + |
| 5 | +## Vector3 |
| 6 | + |
| 7 | +A set of free functions and a wrapper class for common vector3 operations. Two distinct patterns are supported, a more pure computational approach operating on the Vector3 interface with no mutation, and a separate wrapper object oriented approach following a "builder" pattern. It is mostly preference whether you prefer the more "mutation" heavy pattern or the functional pattern, so it depends on the structure of your code. Under the covers, the same helpers are used. |
| 8 | + |
| 9 | +### Pure Functional Style |
| 10 | + |
| 11 | +```ts |
| 12 | +import { Vector3, world } from '@minecraft/server'; |
| 13 | +import { MinecraftDimensionTypes } from '@minecraft/vanilla-data'; |
| 14 | +import { add, subtract, cross } from '@minecraft/math'; |
| 15 | + |
| 16 | +const vectorA: Vector3 = {x: 1, y: 2, z:3}; |
| 17 | +const vectorB: Vector3 = {x: 4, y: 5, z:6}; |
| 18 | + |
| 19 | +const resultAdd = add(vectorA, vectorB); // {x:5, y:7, z:9} |
| 20 | +const resultSubtract = subtract(vectorA, vectorB); // {x:-3, y:-3, z:-3} |
| 21 | +const resultAdd = cross(vectorA, vectorB); // {x:-3, y:6, z:-3} |
| 22 | + |
| 23 | +console.log(toString(vectorA)); // Prints out "1, 2, 3" |
| 24 | + |
| 25 | +// Use your vectors with any @minecraft/server API |
| 26 | +const = dimension = world.getDimension(MinecraftDimensionTypes.Overworld); |
| 27 | +dimension.spawnParticle("minecraft:colored_flame_particle", resultAdd); |
| 28 | +``` |
| 29 | + |
| 30 | +### Builder Style |
| 31 | + |
| 32 | +```ts |
| 33 | +import { Vector3, world } from '@minecraft/server'; |
| 34 | +import { Vector3Builder } from '@minecraft/math'; |
| 35 | +import { MinecraftDimensionTypes } from '@minecraft/vanilla-data'; |
| 36 | + |
| 37 | +const vectorA: Vector3Builder = new Vector3Builder({x: 1, y: 2, z:3}); |
| 38 | +const vectorB: Vector3 = {x: 4, y: 5, z:6}; |
| 39 | +const vectorC: Vector3 = {x: 1, y: 3, z:5}; |
| 40 | + |
| 41 | +// Mutates vectorA directly each time |
| 42 | +vectorA.add(vectorB).subtract(vectorC).cross(vectorB); // Final result {x:4, y:-8, z:4} |
| 43 | + |
| 44 | +console.log(vectorA.toString()); // Prints out "4, -8, 4" |
| 45 | + |
| 46 | +// Vector3Builder type can directly be used in APIs that accept Vector3 |
| 47 | +const dimension = world.getDimension(MinecraftDimensionTypes.Overworld); |
| 48 | +dimension.spawnParticle("minecraft:colored_flame_particle", vectorA); |
| 49 | +``` |
| 50 | + |
| 51 | +## How to use @minecraft/math in your project |
| 52 | + |
| 53 | +@minecraft/math is published to NPM and follows standard semver semantics. To use it in your project, there are two main options: |
| 54 | + |
| 55 | +1. Download `@minecraft/math` from NPM by doing `npm install @minecraft/math` within your scripts pack. By using `@minecraft/math`, you will need to do some sort of bundling to merge the library into your packs code. We recommend using [esbuild](https://esbuild.github.io/getting-started/#your-first-bundle) for simplicity. |
| 56 | +2. This repository publishes releases for `@minecraft/math`, and on each release we attach a pre-bundled copy of the `@minecraft/math` module. Feel free to take this JS bundle and integrate into your projects as it contains all dependencies coupled together, and this pattern does not require bundling. |
0 commit comments