README

Project Overview

This project showcases an interactive WebGL scene featuring:

• A 3D World with ground, sky, walls, and a textured environment.
• A Movable Camera that uses pointer-lock to enable first-person style viewing, complete with collision handling so you can't pass through walls.
• Lighting with both a global point light and a spotlight (Phong shading) to highlight objects in a cone. The spotlight and point light can be toggled and repositioned via UI sliders.
• Animated "Cockroach"-like creature (built from multiple cubes and spheres), including moving legs and antennas. Various transformations let it appear to walk and interact within the scene.
• UI Controls for toggling normals, lighting, and adjusting positions of lights and animations. The canvas appears on the left, while all textual controls and information are organized to the right.

Key Features

1. WebGL Shaders

   • Vertex Shader: Transforms vertices into clip space and passes normals/UVs to the fragment shader.
   • Fragment Shader: Implements ambient, diffuse, and specular (Phong) lighting for the global light source, and adds a spotlight contribution (with its own position, direction, cutoff, and exponent) to the overall scene lighting.

2. Spotlight Implementation

   • A second light source with dedicated uniforms for position, direction, cutoff angle, and exponent.
   • The spotlight’s contribution is added to the global light rather than replacing it.

3. Scene Objects

   • Cube and Sphere classes manage geometry, normals, UVs, and include a render() method.
   • The “cockroach” model is constructed from multiple cubes and spheres (body, head, legs, eyes, antennas).
   • The environment includes a ground plane, sky, and walls/maze generated from a map array.

4. Camera and Collision

   • A first-person camera controlled via pointer lock and keyboard (W, A, S, D).
   • Collision detection prevents walking through walls and going below ground.
   • Smooth sliding along walls is implemented for a more natural movement.

5. Animation and UI

   • UI sliders allow adjustment of the global light and spotlight positions along the X, Y, and Z axes.
   • Buttons to toggle normals, regular lighting, spotlight, and leg-swing animations.
   • The HTML/CSS layout positions the canvas on the left and all controls and text on the right.

How to Run

1. Open World.html in a modern WebGL-capable browser.
2. Click the canvas to engage pointer lock.
3. Use the keyboard (W, A, S, D or arrow keys) to move around. Press Tab or Esc to release pointer lock.
4. Use the UI controls on the right to:
   • Toggle normals on/off.
   • Turn the global light and spotlight on/off.
   • Adjust the positions of the lights using the sliders.
   • Toggle the leg-swing animation.
5. Observe the dynamic lighting (global and spotlight) and animated objects in the scene.

Technical Details

• Shaders:

  • The Vertex Shader handles transformations and passes texture coordinates (UV) and normals.
  • The Fragment Shader calculates Phong lighting for both the global light and the spotlight (which adds to the overall lighting).

• Buffer Management:

  • Separate buffers exist for geometry, UV coordinates, and normals.
  • Helper functions (e.g., drawTriangle3DUVNormal()) ensure correct buffer binding and attribute pointer setup.

• Matrix Transformations:

  • Model, view, and projection matrices transform objects correctly.
  • Hierarchical transformations are applied for animating body parts of the creature.

Project Structure

• World.html
  The main HTML file that loads all scripts, displays the canvas, and organizes UI controls.
• World.js
  Contains the main logic for initializing WebGL, connecting shaders, and handling the render loop.
• Render.js
  Implements renderAllShapes(), setting up transformation matrices and drawing scene objects.
• Camera.js
  Implements the camera movement, pointer lock handling, and collision detection.
• Cube.js and Sphere.js
  Define the 3D primitives and their rendering routines.
• Triangle.js
  Contains helper functions for drawing triangles.
• StaticVariables.js
  Manages global transformation matrices and object instances for the scene.

Collaboration and AI Usage

• Collaboration:
  • Worked closely with Sam Morrow to discuss project requirements, refine the spotlight implementation, and debug the hierarchical animations.
• AI Tools:
  • ChatGPT assisted in understanding and implementing the spotlight math, Phong shading, and in reformatting the HTML/CSS layout.
  • GitHub Copilot provided auto-completion suggestions, which were thoroughly reviewed and tested.
• Manual Debugging:
  • All AI-generated suggestions were manually debugged and refined to ensure correctness and optimal performance.

Lessons Learned

• Implementing a combined lighting model (global point light + spotlight) using Phong shading.
• Effective hierarchical modeling and animation of complex objects.
• Managing first-person camera movement with collision detection.
• Organizing UI elements to create a user-friendly interface.

Setup / Dependencies

• Open the project directly in a modern browser with WebGL support.
• No additional external libraries are needed beyond the provided utility scripts (e.g., cuon-utils.js).

---

Enjoy exploring the 3D scene!
Feel free to experiment by adjusting light parameters, adding more animations, or extending the environment further.