# GamesJi Top War

An original **merge-strategy browser game** — merge soldiers, tanks and helicopters, build and upgrade your headquarters, and battle through 100 campaign levels. Built with plain HTML5, CSS3 and vanilla JavaScript: **no frameworks, no build step, no npm, works fully offline.**

Publish path: `https://gamesji.com/topwar/`

> This is an original game inspired by the general "merge strategy" genre. No assets, UI, code, text, characters or maps were copied from any existing game — every icon, background, sound effect and music track in this project was generated from scratch for GamesJi (see **Asset Origins** below).

---

## 1. Quick Start (Deployment)

1. Unzip the archive.
2. Upload the **contents** of the folder (not the folder itself) to `/public_html/topwar/` on your host.
3. Visit `https://gamesji.com/topwar/` — that's it. No build step, no server-side code, no database.
4. The game works over plain static hosting (Apache, Nginx, GitHub Pages, Netlify, Cloudflare Pages, etc.) — it only needs files served over HTTP(S). It also passes fully offline once a player has visited once (service worker caching).

**Local testing:** because the game uses `fetch()` for audio decoding and registers a Service Worker, opening `index.html` directly via `file://` will not work fully in most browsers. Serve it with any static file server while testing, e.g.:
```
python3 -m http.server 8080
# then open http://localhost:8080/
```

---

## 2. Project Structure

```
topwar/
├── index.html          All screens/markup (loading, splash, HUD, base, map, battle, modals)
├── style.css            Full design system + responsive layout + animations
├── script.js             Game engine (config, save system, audio, merge logic, battle sim, UI)
├── manifest.json        PWA manifest (installable app)
├── sw.js                 Service worker (offline caching)
├── favicon.ico
├── README.md
└── assets/
    ├── images/           Buildings, units, resources, backgrounds, OG share image, app logo
    ├── icons/             UI glyphs + PWA icons (192/512/maskable/apple-touch/favicons)
    ├── sounds/            Short SFX (merge, click, explosion, victory, defeat, …) — .mp3
    ├── music/             Looping background tracks (menu / battle / victory) — .mp3
    └── fonts/             Bundled open-license font + its license text
```

No other files are required. Nothing is loaded from a CDN or any external domain — open DevTools → Network on a fresh load and every request resolves to a local file.

---

## 3. Gameplay Overview

- **Base**: upgrade 10 building types (HQ, Barracks, Factory, Airport, Garage, Research Lab, Radar, Power Plant, Warehouse, Hospital). Each building is upgradable and gated by your Headquarters level — raising HQ unlocks higher levels everywhere else.
- **Merge Yard**: three merge lines — Ground (Infantry → Sniper → Heavy Soldier), Armor (Tank → Heavy Tank → Rocket Tank), Air (Helicopter → Missile Helicopter → Drone). Recruit a base unit with Energy, then drag one unit onto a matching unit/level to merge them into something stronger.
- **Campaign**: 100 levels across 10 themed chapters, with a boss fight every 10th level. Levels are generated from a scaling difficulty formula (enemy count, enemy level and unlocked enemy unit types all scale with progress), so difficulty rises smoothly across the whole campaign rather than needing 100 hand-tuned entries.
- **Battle**: real-time, auto-attacking combat on a canvas battlefield. Units path to the nearest enemy, attack in range, show floating damage numbers, health bars and death explosions. Win by defeating the enemy army; reinforce mid-fight for a small Fuel cost.
- **Meta progression**: achievements with claimable rewards, 7-day daily login rewards, offline earnings (Power Plant + Warehouse), a Shop with rewarded-ad and diamond-exchange placeholders.
- **Save system**: everything autosaves to `localStorage` every 15 seconds, on tab-hide, and before unload. "Reset Progress" is available in Settings.

---

## 4. Ads, Analytics & Monetization — Integration Points

Per the project spec, **no ad network SDK or analytics script is bundled.** Clearly-labeled placeholders are wired up so you can drop in real code later without touching game logic:

| Placeholder | Where | What to do |
|---|---|---|
| Top banner | `#ad-slot-top` in `index.html` | Replace the dashed placeholder `<div>` with your AdSense unit. |
| Bottom banner | `#ad-slot-bottom` in `index.html` | Same as above. |
| Rewarded video | `showRewardedAd()` in `script.js` | Replace the `setTimeout` simulation with your ad SDK's rewarded-video call. Search `INTEGRATION POINT` in `script.js`. |
| Interstitial | `showInterstitialAd()` in `script.js` | Replace the manual "Continue" button with your SDK's close callback. Shown automatically every 3rd battle. |
| Analytics | `trackEvent()` in `script.js` | Add the GA4 snippet (with your Measurement ID) to `index.html`'s `<head>`, then swap the `console.log` for `gtag('event', ...)`. Already called at key funnel points: level complete, level failed, ad start/complete. |

Search the codebase for `INTEGRATION POINT` to find every spot at a glance.

---

## 5. Technical Notes

- **Zero dependencies.** No React/Vue, no bundler, no `node_modules` required to run the game itself (Node/Playwright were only used during development for testing, not shipped).
- **Rendering**: DOM/CSS for menus and HUD, a single `<canvas>` for the real-time battle scene, drawn with `requestAnimationFrame` and delta-time so combat speed is frame-rate independent.
- **Input**: unified Pointer Events power the merge-yard drag-and-drop, so the same code path handles mouse, touch and stylus.
- **Performance**: unit sprites are pre-composited onto small offscreen canvases once at load time (per unit type × team color) instead of re-tinting every frame; battle entity counts stay in the dozens, not hundreds, to comfortably hold 60fps on mid-range phones; all animations are CSS transform/opacity based (GPU-friendly) apart from the battle canvas itself.
- **Responsive**: mobile-first with a dedicated landscape layout (base/merge panels go side-by-side, HUD shrinks) and a centered max-width shell on tablets/desktop so it still reads as an app rather than stretching edge to edge.
- **PWA**: `manifest.json` + `sw.js` give installability and offline play after the first visit. The service worker precaches every shipped file and serves cache-first with a network fallback.
- **Accessibility**: focus-visible outlines on all interactive elements, `prefers-reduced-motion` respected, alt text on informative images, ARIA roles on modals/progressbars.

---

## 6. Asset Origins (Originality & Licensing)

Everything under `assets/` was produced specifically for this project — nothing was downloaded from the reference game or any third party:

- **Images/Icons** (`assets/images`, `assets/icons`): procedurally drawn with Python/Pillow from geometric primitives (no traced or copied artwork), then hand-tuned for this game's own color palette.
- **Sounds & Music** (`assets/sounds`, `assets/music`): synthesized from scratch with raw sine/square/triangle oscillators and noise (no sampled or licensed audio), then compressed to MP3.
- **Font** (`assets/fonts`): "Liberation Sans", distributed under the **SIL Open Font License 1.1**, which explicitly permits bundling and embedding. The full license text is included at `assets/fonts/OFL-LICENSE.txt` as required by that license.

Because every binary asset is either generated code output or an explicitly redistributable open-license font, the whole package is safe to publish as-is.

---

## 7. Customization Guide

Almost all game balance lives in clearly-commented data tables near the top of `script.js`:

- `BUILDING_DEFS` — costs, growth rate, max level, and effect-per-level for every building.
- `UNIT_DEFS` / `UNIT_LINES` — base stats and merge lines for all 9 units.
- `generateLevel()` / `CHAPTER_UNIT_POOL` / `CHAPTER_NAMES` — campaign difficulty curve and chapter theming. Change the formulas here to re-balance all 100 levels at once, or hand-edit specific entries in the generated `LEVELS` array.
- `ACHIEVEMENT_DEFS`, `DAILY_REWARDS`, `SHOP_ITEMS` — meta-game content, each a plain array of objects.
- `style.css` `:root` custom properties at the top of the file — the entire color palette, radii and spacing scale in one place.

## 8. Browser Support

Tested against current Chromium-based mobile/desktop browsers. Uses standard, broadly-supported Web APIs only: Canvas 2D, Web Audio API, Pointer Events, `localStorage`, Service Worker, Web App Manifest. No experimental or vendor-prefixed APIs are required.

---

Built for **GamesJi**. Have fun commanding the battlefield!
