Documentation

Table of Contents

• Code Comments
• Mini-Lesson Documentation
• Code Highlights

Documentation is the process of explaining how code works so other people can understand, use, and improve it. Good documentation makes a program easier to read because it connects the code to the ideas behind it.

Code Comments

Code comments are notes written inside a program to explain what the code is doing. They are useful when a section of code has important logic that may not be obvious from the code alone.

JSDoc comments are a structured type of comment used in JavaScript. They can describe what a class does, what parameters a method takes, and what value a method returns.

%%js

/**
 * Represents a gravity-based platform level in the game engine.
 * The level owns platform layout, player physics, collectibles, and win/death checks.
 */
class GravityLevel {
  /**
   * Creates a new gravity level.
   * @param {Object} gameEnv - Shared game environment containing size, path, and game objects.
   */
  constructor(gameEnv) {
    this.gameEnv = gameEnv;
    this.gravity = 0.52;
    this.maxFall = 15;
  }

  /**
   * Applies gravity to the current vertical velocity.
   * @param {number} velocityY - Current vertical velocity.
   * @returns {number} New vertical velocity after gravity and fall-speed cap.
   */
  applyGravity(velocityY) {
    return Math.min(velocityY + this.gravity, this.maxFall);
  }
}

Mini-Lesson Documentation

Mini-lesson documentation teaches one small concept using a short explanation, an example, and something visual or interactive. It helps the reader learn a specific idea without needing to understand the entire program at once.

This mini-lesson uses the Crater Falls game level to explain gravity. In GameLevel3.js, the player has a vertical velocity called _vy. When the player jumps, _vy is set to JUMP_FORCE, which is negative so the player moves upward. Every physics frame, gravity is added to _vy, which pulls the player back down. MAX_FALL prevents the player from accelerating forever.

The level runs its physics loop every 16 milliseconds. After gravity changes _vy, the game calculates a proposed next position with ny = py + self._vy. Platform collision then decides whether the player landed, hit a ceiling, hit a wall, fell into the crater, touched spikes, collected coins, or reached the flag.

Use the embedded demo below to test the lesson: jump with W, Space, or the up arrow, then watch how the player rises, slows down, falls, and lands on platforms.

Code Highlights

Code highlights are selected parts of a program that show the most important ideas in the code. Instead of showing every line of code, highlights focus on the sections that best explain how the program works.

Highlighted code can show object-oriented programming, imports between files, gravity, and collision detection. Each highlight should connect the snippet to the behavior the player sees in the game.

%%js

// OOP highlight: a level class stores the state and behavior
// for one complete level: platforms, coins, physics, win checks, and cleanup.
class ExampleGameLevel {
  constructor(gameEnv) {
    this.gameEnv = gameEnv;
    this._vy = 0;
    this._vx = 0;
    this._onGround = false;
    this._coins = 0;
  }
}

// API/import highlight from the live game demo:
// import { GameControl } from '/assets/js/GameEnginev1.1/essentials/Imports.js';
// import GameLevel3 from '/assets/js/GameEnginev1.1/essentials/GameLevel3.js';

// Gravity highlight: vertical velocity changes every frame.
// Jump force pushes up because it is negative; gravity pulls down by adding.
self._vy = Math.min(self._vy + GRAVITY, MAX_FALL);
let ny = py + self._vy;

// Collision highlight: landing happens when the player's feet cross a platform top.
// The game snaps the player to the platform, stops falling, and marks them grounded.
if (withinX && prevFeet <= psy + 2 && newFeet >= psy) {
  ny = psy - ph;
  self._vy = 0;
  self._onGround = true;
}