A powerful 3D vector simulation and visualization library built with Three.js for educational purposes. VectorPlay makes it easy to visualize vectors, coordinate systems, and mathematical operations in 3D space.

• 🎯 3D Vector Visualization: Render vectors as arrows in 3D space
• 📐 Mathematical Operations: Visualize vector addition, subtraction, cross products, scaling, and projections
• 🧮 Vector Calculations: Dot products, magnitude calculation, and unit vector generation
• 🏷️ Point and Label System: Add labeled points and coordinate displays
• 🎮 Interactive Controls: Built-in orbit controls for exploring 3D scenes
• 📏 Grid and Axis Helpers: Visual reference system with customizable grid and axes
• 🎨 Customizable Appearance: Configure colors, sizes, and styling

Peer Dependencies: Make sure you have Three.js installed:

# Create in new directory
npx vectorplay@latest create my-vector-app
cd my-vector-app
npm run dev
# Or create in current directory
npx vectorplay@latest create .
npm run dev

What this does automatically:

• Creates template files (index.html, main.js, package.json)
• Installs all dependencies (vectorplay, three, vite)
• Sets up the development environment

The main class for creating and managing 3D scenes.

new MainFrame((bg_color = "black"), (grid_length = 100), (axis_length = 7));

Parameters:

• bg_color (string): Background color of the scene
• grid_length (number): Size of the reference grid
• axis_length (number): Length of the coordinate axes

Add a labeled point to the scene.

Parameters:

• x, y, z (number): Coordinates of the point
• name (string): Label for the point (default: "P")
• color (string): Color of the point (default: "red")
• size (number): Size of the point (default: 0.05)

Add a vector to the scene.

Parameters:

• vec (Vector): Vector object to render
• fromOrigin (boolean): Whether to draw from origin (default: true)
• custom_origin (object): Custom starting point {x, y, z}
• color (hex): Color of the vector (default: 0xffff00)

Visualize vector addition by showing both vectors and their sum.

Visualize vector subtraction.

Visualize cross product of two vectors.

Visualize a scaled vector.

Visualize the projection of one vector onto another.

Parameters:

• ofvec1 (Vector): Vector to be projected
• onvec2 (Vector): Vector to project onto

Start the animation loop (call this last).

Represents a 3D vector with mathematical operations.

new Vector(x, y, z);

Add another vector to this vector (modifies the current vector).

Subtract another vector from this vector (modifies the current vector).

Negate the vector (multiply by -1).

Scale the vector by a factor k (modifies the current vector).

Parameters:

• k (number): Scaling factor

Calculate and return the magnitude (length) of the vector.

Returns: number - The magnitude of the vector

Get the unit vector (normalized vector with magnitude 1).

Returns: Vector - A new Vector representing the unit vector

Calculate the dot product with another vector.

Parameters:

• vector (Vector): The other vector

Returns: number - The dot product result

Calculate cross product with another vector (returns new Vector).

import { MainFrame, Vector } from "vectorplay";
const scene = new MainFrame();
const vector = new Vector(3, 4, 2);
scene.addVector(vector);
scene.runInloop();

import { MainFrame, Vector } from "vectorplay";
const scene = new MainFrame("darkblue", 30, 8);
const vec1 = new Vector(2, 3, 1);
const vec2 = new Vector(1, -1, 2);
// Show vector addition
scene.plotSum(vec1, vec2);
scene.runInloop();

import { MainFrame, Vector } from "vectorplay";
const scene = new MainFrame();
const vec1 = new Vector(1, 0, 0);
const vec2 = new Vector(0, 1, 0);
// This will show both input vectors and their cross product
scene.plotCross(vec1, vec2);
scene.runInloop();

import { MainFrame, Vector } from "vectorplay";
const scene = new MainFrame();
const vec1 = new Vector(3, 4, 0); // Vector to project
const vec2 = new Vector(1, 0, 0); // Vector to project onto
// Show both vectors and the projection
scene.addVector(vec1);
scene.addVector(vec2);
scene.plotProjection(vec1, vec2);
scene.runInloop();

import { Vector } from "vectorplay";
const vec1 = new Vector(3, 4, 0);
const vec2 = new Vector(1, 2, 2);
// Calculate magnitude
console.log(`Magnitude of vec1: ${vec1.value()}`); // 5
// Get unit vector
const unitVec = vec1.unitVector();
console.log(`Unit vector:`, unitVec); // Vector with magnitude 1
// Calculate dot product
const dotProduct = vec1.dotProduct(vec2);
console.log(`Dot product: ${dotProduct}`); // 11
// Scale a vector
vec1.scale(2); // vec1 is now (6, 8, 0)

VectorPlay includes a CLI tool for quick project setup:

# Create a new VectorPlay project (automatically installs dependencies)
npx vectorplay@latest create my-vector-app
# Create in current directory (automatically installs dependencies)
npx vectorplay@latest create .
# Show help
npx vectorplay@latest

The CLI will:

• Create index.html, main.js, and package.json files
• Automatically install all dependencies (vectorplay, three, vite)
• Set up a ready-to-run development environment

If automatic setup works: Just run npm run dev after the CLI finishes!

If you need manual setup: Use the 4-step process:

1. npm init -y
2. npm install three vite vectorplay
3. npx vectorplay@latest create .
4. npx vite (to run the app)

For direct browser usage without a bundler:

<!DOCTYPE html>
<html>
 <head>
 <script type="importmap">
 {
 "imports": {
 "three": "https://unpkg.com/three@0.180.0/build/three.module.js",
 "three/examples/jsm/": "https://unpkg.com/three@0.180.0/examples/jsm/"
 }
 }
 </script>
 </head>
 <body>
 <script type="module">
 import { MainFrame, Vector } from "./path/to/vectorplay.js";
 const scene = new MainFrame();
 const vector = new Vector(1, 2, 3);
 scene.addVector(vector);
 scene.runInloop();
 </script>
 </body>
</html>

• Three.js ^0.180.0
• Modern browser with ES6 module support
• WebGL support

If you encounter any issues or have feature requests, please file them in the GitHub Issues.