Documentation

Table of Contents

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.

Game Status: Not Started

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

// Imports from GameLevel3.js
import GameEnvBackground from './GameEnvBackground.js';
import Player from './Player.js';

// Class and constructor state from GameLevel3.js
class GameLevel3 {
  constructor(gameEnv) {
    this._physicsInterval  = null;
    this._overlays         = [];
    this._styleEl          = null;
    this._hud              = null;
    this._deathScreen      = null;
    this._isDead           = false;
    this._won              = false;

    this._vy             = 0;
    this._vx             = 0;
    this._onGround       = false;
    this._canJump        = true;
    this._onMovingPlat   = false;
    this._movingPlatVelX = 0;
    this._lives          = 3;
    this._coins          = 0;
  }
}

// Game object classes from GameLevel3.js
this.classes = [
  { class: GameEnvBackground, data: bgData    },
  { class: Player,            data: playerData },
];

// Physics loop and gravity from GameLevel3.js
this._physicsInterval = setInterval(() => {
  if (self._isDead || self._won) return;

  const player = gameEnv.gameObjects.find(o => o instanceof Player);
  if (!player) return;

  self._vy = Math.min(self._vy + GRAVITY, MAX_FALL);

  let nx = px + self._vx;
  let ny = py + self._vy;
}, 16);

// Platform landing collision from GameLevel3.js
if (self._vy >= 0) {
  const prevFeet = py + ph;
  const newFeet  = ny + ph;
  const withinX  = nx + pw*0.15 < psx+psw && nx + pw*0.85 > psx;
  if (withinX && prevFeet <= psy+2 && newFeet >= psy) {
    ny = psy - ph;
    self._vy = 0;
    self._onGround = true;
    if (p.id === 'p3_move') self._onMovingPlat = true;
  }
}

// Coin collection from GameLevel3.js
for (const c of self._coinPositions) {
  if (c.collected) continue;
  if (pcx > c.x && pcx < c.x+c.w && pcy > c.y && pcy < c.y+c.h) {
    c.collected = true;
    c._el.style.opacity = '0';
    c._el.style.transition = 'opacity 0.3s';
    setTimeout(()=>c._el.remove(), 350);
    self._coins++;
    self._updateHud();
  }
}

// Cleanup and exports from GameLevel3.js
this.destroy = () => {
  if (this._physicsInterval) { clearInterval(this._physicsInterval); this._physicsInterval=null; }
  document.removeEventListener('keydown', this._keyDown);
  document.removeEventListener('keyup',   this._keyUp);
  for (const el of this._overlays) { try { el.remove(); } catch(_){} }
  this._overlays = [];
};

export const gameLevelClasses = [GameLevel3];
export default GameLevel3;

Explanation - These highlights all come from GameLevel3.js. The imports show that the level uses existing game pieces, like the background and player, instead of making everything again. The starting variables keep track of important gameplay details like movement, lives, coins, and whether the player has won or died.

The physics loop is the part that keeps the level moving. It updates the player’s movement, applies gravity, and checks if the player landed on a platform. When the player lands, the game places them on top of the platform and lets them jump again.

The coin code checks if the player touched a coin. When that happens, the coin disappears and the HUD updates. The cleanup code is also important because it removes old timers, key controls, and screen elements when the level ends.