Tower Defense — Design & Contribution Guide

This document describes the current Tower Defense implementation (see levels/towerDefense/towerDefense.js), how the core Game class works, and how to add towers, enemies, and features.

For this project, keep gameplay code in the same file for now. When adding new behavior, add new classes in towerDefense.js rather than creating new folders.

Overview

The Game class manages board state (grid, path), rendering, and input. The board is a grid of boardHeight × boardWidth cells. The path for enemies is generated by drawEnemyPath() and stored in this.path as an array of [row, col] coordinates. Towers and enemies are plain objects stored in this.towers and this.enemies.

Key responsibilities in Game:

• layout & sizing: resize() computes cellSize, offsetX, offsetY.
• board and path initialization: reset() and drawEnemyPath().
• rendering: drawBackground(), drawPath(), draw().
• input: handleCanvasClick() → handleClick() (translates canvas coords to row/col).
• simple mutation API: addTower(tower) and addEnemy(enemy).

Coordinate system

• Board coordinates are integers: row (0..boardHeight-1) and col (0..boardWidth-1).
• Canvas coordinates are translated to board coordinates using offsetX, offsetY, and cellSize.

Rendering notes

• Path cells are painted in drawPath() using the this.board markers.
• Towers are painted as filled squares inside a cell.
• Enemies are painted as circles centered inside a cell.

Data shapes (conventions)

Tower (example shape)

{
	id: 'basic-1',        // unique id
	row: 4,               // integer board row
	col: 2,               // integer board col
	range: 2.5,           // in cells (floating OK)
	fireRate: 1.0,        // shots per second
	damage: 1,            // damage per shot
	update: function(game, dt) { ... } // optional per-tower update method
}

Enemy (example shape)

{
	id: 'goblin-1',       // unique id
	hp: 3,                // hit points
	speed: 1.0,           // cells per second (recommended)
	pathIndex: 0,         // index into game.path (which cell the enemy is moving toward)
	progress: 0.0,        // 0..1 progress between path[pathIndex] and path[pathIndex+1]
	update: function(game, dt) { ... } // advance along path, handle death
}

How enemies should work (recommended)

• Each enemy stores pathIndex (current segment) and progress (0..1) or a position in canvas pixels.
• On each game tick/update, call enemy.update(game, dt):
  • advance progress by speed * dt / 1cellLength.
  • when progress >= 1 increment pathIndex and set progress -= 1.
  • if pathIndex reaches game.path.length - 1, the enemy reached the base → apply damage/coin penalty and remove enemy.
  • compute render row/col (or pixel position) by interpolating between current and next path cell.
• When an enemy’s hp <= 0, remove it and award coins as appropriate.

How towers should work (recommended)

• Each tower has range, fireRate, damage and a local cooldown timer (use lastShotAt or cooldown value).
• On each tick/update, tower.update(game, dt) should:
  • find enemies within range (distance in cells between tower center and enemy position).
  • select a target using a strategy (closest to base, lowest hp, first in path).
  • if cooldown <= 0, create a projectile or directly apply damage to the enemy, then reset cooldown to 1/fireRate.
• Projectiles (optional): add a small object managed by the game which moves and applies damage on hit.

Where to implement behaviors

• Organized approach: create classes:
  • Towers — tower classes/factories (e.g. basicTower, sniperTower)
  • enemies — enemy classes/factories (e.g. goblin, troll)
  • projectiles — projectile behaviors. (e.g. cool bullets)
  • spawners — code to spawn waves/levels of enemies
• Place towers via game.addTower(createBasicTower(4,2)) or via click-handling code.

Best practices and conventions

• Keep game state deterministic where possible — use consistent tick-based updates (dt in seconds) rather than relying on absolute timestamps.
• Keep rendering separate from state updates: compute positions in update() and draw in draw().
• Use small single-responsibility modules for tower and enemy behavior.
• Prefix level-specific modules under levels/towerDefense/ to avoid namespace collisions.

Planned features and notes (ideas to implement next)

• Projectile system: make towers spawn projectile objects that travel and hit enemies.
• Path smoothing & pixel-accurate positions so enemies move smoothly between cells.
• Wave spawner & level data format (JSON) so designers can author waves.
• Tower upgrades, cost system, and UI to build/place towers (coins are present in Game.coins).
• Better input: right-click to sell, left-click to place, drag-to-pan, touch support.

Testing locally

• Start a local preview/serve (follow repo Makefile and README). Run the page that instantiates the level and open the browser console for logs — drawEnemyPath() currently logs out the generated path.

Contact & ownership

• If you add API-breaking changes, update this document and add a short example demonstrating the new API.

If you’d like, I can also:

• implement a minimal Enemy and Tower class in towerDefense.js and wire them into Game.update() as a concrete example,
• add a demo spawner in the same file so new enemies can be tested quickly.