# Tower Defense 3D (RSK World)

Strategic 3D tower defense game with animated enemies, village building, resources, and upgrades. Built with Three.js and ES modules.

![Tower Defense](tower-defense.png)

---

## Quick Start (Laragon / Localhost)

1. Place the project under your Laragon web root, e.g.
   - `https://rskworld.in/games/html5-games/tower-defense/`
2. Start Laragon/Apache.
3. Open in your browser:
   - `https://rskworld.in/games/html5-games/tower-defense/index.php`
4. Press “Start Wave” to begin. Use the toolbar to build and interact.

Requirements:
- Modern Chromium/Firefox/Safari browser (supports import maps & ES modules)
- Internet access (CDN for Three.js examples)

---

## Features

- 3D scene (Three.js) with orbit controls, lights, fog, and shadows
- Multi-lane enemy pathing (center/left/right lanes)
- Animated enemies (GLTF-ready) and stylized toon fallback
- Towers with aiming and firing (instant-hit + tracer for reliability)
- Walls (destructible) and enemies attack obstacles
- Village environment (Town Hall, huts) and instanced trees
- Resources: Gold and Elixir with production buildings
  - Gold Mine (Gold), Elixir Collector (Elixir), Storage
- Barracks and unit training (Barbarian) using Elixir
- Villagers with wandering behavior
- Hero (WASD) spawn and movement
- Upgrades: select a tower/wall to upgrade (range, fire rate, damage, wall HP)
- Grid placement with collision and path proximity checks
- Day/Night toggle and a grouped, responsive toolbar
- Save/Load to localStorage
- Full-screen game menu (Play/Continue)
- Diagnostics: debug logs for wave start, spawns, placement, and tower firing

---

## Controls & UI

Top HUD (pill style):
- Gold, Elixir, Builders, Lives, Wave

Toolbar (grouped into three rows):
- Start Wave: begin spawning enemies
- Train Barbarian (50 Elixir): enqueues training if Barracks exists
- Spawn Villager: adds a wandering villager
- Build Cannon (100): toggle tower build mode, click ground to place
- Build Wall (50): toggle wall build mode, click ground to place
- Gold Mine (150) / Elixir Collector (150) / Storage (200): building placement
- Barracks (250): required to train Barbarians
- Night Mode: toggle day/night lighting & tone mapping
- Save & Load: persist/restore to/from localStorage
- Menu: open full-screen overlay

Selection & Upgrades:
- Click an existing tower/wall/building to select it.
- Upgrade button shows level and cost when available.

Hero:
- Click “Spawn Hero” (appears on Start Wave for diagnostics)
- Move with WASD

Placement rules:
- Grid-snapped placement
- Cannot place on occupied cells
- Must be slightly away from the path (threshold kept lenient for interaction)

---

## Configuration

Main configuration is in `assets/js/main.js` inside `GameConfig`:

- Costs: `costs: { tower, wall, mine, collector, storage }`
- Rendering pixel ratio: `renderPixelRatio`
- GLTF models (sample): `villagerModelUrl`
- Enemy types (COC-like): `enemyTypes`
  - You can point each `url` to your GLTF/GLB and tune `scale`, `speed`, `health`, `radius`, `animName`.

Enemy models:
- The game supports two modes:
  1) GLTF enemies via `EnemyGLTF` (use model `url`)
  2) Stylized toon enemies via `EnemyToon` (no model url required)

To use your own GLTF/GLB files, replace the URLs in `GameConfig.enemyTypes`.

Resources logic:
- Centralized in `assets/js/components/Resources.js` (`ResourceState`)
- Always use the helper methods: `spendGold`, `earnGold`, `spendElixir`, `earnElixir`

Upgrades:
- `assets/js/components/UpgradeSystem.js` – adjust level caps, multipliers, and costs

Village & Environment:
- `assets/js/components/Village.js` – TownHall + Huts, default location near map edge
- `assets/js/components/Environment.js` – instanced trees scattered away from path

---

## File Structure

```
assets/
  css/style.css                # UI/UX styles, HUD, toolbar, overlay menu
  img/tower-defense.png        # Icon/preview
  js/
    main.js                    # Game bootstrap, loop, state, UI wiring
    components/
      Path.js                  # Path & lane helpers
      Enemy.js                 # Base enemy (capsule) + obstacle attack
      EnemyGLTF.js             # GLTF-based enemy with animation
      EnemyToon.js             # Stylized toon enemy
      EnemyFactory.js          # Spawns enemies per configured type
      Tower.js                 # Tower entity, aiming, firing (instant-hit + tracer)
      Projectile.js            # Visual projectile (tracer)
      Wall.js                  # Destructible wall
      WaveManager.js           # Wave spawning scheduler
      UIManager.js             # Buttons, hints, selection/upgrade UI
      Environment.js           # Trees (instanced meshes)
      Village.js               # Town Hall + Huts
      Resources.js             # Resource state + production buildings
      Barracks.js              # Trains units (barbarian)
      AllyUnit.js              # Simple melee ally
      UpgradeSystem.js         # Upgrades & selection highlight
      Grid.js                  # Grid occupancy for placement
index.php                      # App shell (import map, HUD, toolbar, menu overlay)
README.md                      # This document
meta.php / game.json           # Game metadata
```

---

## Troubleshooting

- Nothing renders / blank canvas:
  - Hard refresh (Ctrl+F5). Ensure internet (Three.js CDN) and modern browser.
  - Check console for import-map or module errors.
- HUD “Gold/Elixir…” not changing:
  - Deduction happens on placement (click a build button, then click ground to place).
  - We throttle passive updates to ~4/s; actions force immediate refresh.
  - If pills don’t update, check for console errors pointing to missing HUD elements.
- Tower not firing:
  - Click “Start Wave”. Enemies must be moving.
  - Place a tower near a lane (you can place closer to the path now).
  - Towers use instant-hit damage and also spawn a tracer for visuals.
  - Open console; you should see logs: “Starting wave…”, “Spawned enemy…”, “Tower fired…”.
- Still stuck?
  - Copy the first console error and share it; we’ll fix quickly.

---

## Customization Tips

- Replace GLTF model URLs for enemies/villagers with your assets.
- Tune tower `fireCooldown`, `damageMultiplier`, projectile visuals in `Tower.js` and `Projectile.js`.
- Change path shape in `Path.js` or add more lanes via `createOffsetPath`.
- Adjust placement proximity rules and grid size in `main.js`/`Grid.js`.
- Update styles in `assets/css/style.css` for branding and layout.

---

## Contact / Support

For support, licensing, or custom development inquiries: **help@rskworld.in**
Phone/WhatsApp: **+91 9330539277**
Website: **RSK World**
Business Inquiries: **help@rskworld.in**

🤝 Contributing: Suggestions and improvements are welcome!

---

## License

© RSK World. All rights reserved unless otherwise stated.
