Interactive Projectile Motion Simulation

An educational physics simulation for exploring projectile motion concepts through interactive visualizations and hands-on experimentation.

Features

🎯 Interactive Simulation

• Real-time projectile motion visualization using p5.js
• Adjustable parameters: initial speed (0-50 m/s), launch angle (0-90°), initial height (0-10 m)
• Vector visualization showing velocity components
• Trajectory path tracing
• Live variable table with physics calculations

📊 Educational Tools

• Challenge Mode: Hide variables and test student predictions
• Assessment System: Star-based scoring with 2% error tolerance for 3 stars
• Progress Tracking: Save student progress locally
• Real-time Calculations: All physics values updated every frame

📱 Responsive Design

• Optimized for Canvas LMS embedding (800×600 iframe)
• Mobile-friendly responsive layout
• Accessible controls and clear visual hierarchy
• Works on desktop, tablet, and mobile devices

🧮 Accurate Physics

• Professional-grade kinematic equations
• Proper gravitational acceleration (-9.8 m/s²)
• Range, maximum height, and flight time calculations
• World-to-screen coordinate conversion (1m = 50px)

Quick Start

1. Direct Browser Use

# Clone the repository
git clone https://github.com/your-username/projectile-motion-sim.git
cd projectile-motion-sim

# Serve locally (Python 3)
python3 -m http.server 8000

# Or with Python 2
python -m SimpleHTTPServer 8000

# Open http://localhost:8000 in your browser

2. GitHub Pages Deployment

1. Fork this repository
2. Enable GitHub Pages in repository settings
3. Set source to "Deploy from a branch" → main → / (root)
4. Access at: https://your-username.github.io/projectile-motion-sim/

3. Canvas LMS Integration

<iframe 
    src="https://your-username.github.io/projectile-motion-sim/" 
    width="800" 
    height="600" 
    style="border: 1px solid #ccc;">
</iframe>

Project Structure

projectile-motion-sim/
├── index.html              # Main HTML page
├── css/
│   └── styles.css          # Responsive CSS with custom properties
├── js/
│   ├── main.js             # p5.js sketch and main simulation loop
│   ├── physics.js          # Physics calculations and helper functions
│   ├── ui.js               # UI controls and state management
│   └── assessment.js       # Challenge mode and progress tracking
├── tests/
│   └── physics.test.js     # Jest test suite for physics functions
├── package.json            # NPM configuration and scripts
├── README.md               # This file
└── .github/
    └── copilot-instructions.md # GitHub Copilot customization

Physics Implementation

Core Equations

// Horizontal position: x = v₀ₓ × t
export function horizPos(v0x, t) { return v0x * t; }

// Vertical position: y = y₀ + v₀ᵧ×t + ½gt²
export function vertPos(y0, v0y, t) { return y0 + v0y*t + 0.5*g*t*t; }

// Vertical velocity: vᵧ = v₀ᵧ + gt
export function vertVel(v0y, t) { return v0y + g*t; }

Calculated Values

• Range: Horizontal distance traveled
• Maximum Height: Peak altitude reached
• Flight Time: Total time in air
• Velocity Components: vₓ and vᵧ throughout flight

Educational Modules

✅ Module 1: Horizontal Launch (Implemented)

• Projectiles launched horizontally from a height
• Focus on x-y motion independence
• Challenge problems with range and flight time predictions

✅ Module 2: Angled Launch (Implemented)

• Full 2D projectile motion with launch angles
• Optimal angle exploration (45° for maximum range)
• Vector analysis and trajectory visualization

🚧 Module 3: Advanced Scenarios (TODO)

• Air resistance effects
• Variable gravity environments
• Multiple projectile comparisons
• Target practice mode

🚧 Module 4: Data Analysis (TODO)

• Export trajectory data
• Statistical analysis tools
• Collaborative problem solving
• Teacher dashboard

Testing

Run the comprehensive Jest test suite:

# Install dependencies
npm install

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage

Test Coverage

• ✅ All physics helper functions
• ✅ Coordinate system conversions
• ✅ Edge cases and error conditions
• ✅ Integration tests for complete motion
• ✅ Energy conservation verification

API Reference

Physics Functions

import { horizPos, vertPos, range, maxHeight } from './js/physics.js';

// Calculate range for 30° launch at 25 m/s from 5m height
const totalRange = range(25, 30, 5); // Returns distance in meters

// Get velocity components
const { vx, vy } = velocityComponents(20, 45); // 20 m/s at 45°

UI State Management

import { getCurrentState, updateVariableTable } from './js/ui.js';

// Get current simulation parameters
const state = getCurrentState();
console.log(state.speed, state.angle, state.height);

// Update the live variable display
updateVariableTable({
    time: 2.5,
    x: 35.4,
    y: 12.1,
    vx: 14.1,
    vy: -10.5
});

Assessment System

import { startChallenge, submitAnswer } from './js/assessment.js';

// Start an easy challenge
startChallenge(1); // Level 1 = Easy

// Submit student answer
const result = submitAnswer(42.5);
console.log(result.stars); // 0-3 stars based on accuracy

Browser Compatibility

• ✅ Chrome 60+
• ✅ Firefox 55+
• ✅ Safari 12+
• ✅ Edge 79+
• ✅ Mobile browsers (iOS Safari, Chrome Mobile)

Deployment Options

GitHub Pages (Recommended)

1. Automatic: Push to main branch
2. Custom Domain: Configure in repository settings
3. HTTPS: Automatically enabled

Alternative Hosting

• Netlify: Drag and drop deployment
• Vercel: Git integration
• Canvas LMS: Direct file upload
• Google Sites: Embed via iframe

Contributing

Development Setup

git clone https://github.com/your-username/projectile-motion-sim.git
cd projectile-motion-sim
npm install
npm run serve

Code Standards

• ES6+ modules with JSDoc comments
• Responsive CSS with custom properties
• Comprehensive Jest testing
• Accessible HTML semantic structure

Future Enhancements

• Air resistance toggle
• Multi-projectile comparisons
• Data export functionality
• Teacher analytics dashboard
• Sound effects and animations
• Collaborative features

License

MIT License - see LICENSE file for details.

Support

• 📧 Email: your-email@institution.edu
• 📖 Documentation: GitHub Wiki
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

---

Built with ❤️ for physics education