wildhack_pvz

wildhack_pvz is a web-based Plants vs. Zombies-inspired duel experience built for fast demos, balance iteration, and AI experimentation. The project combines a real-time browser game loop, a live tuning console, and a client-side zombie controller powered by an exported reinforcement learning model.

Live Demo

Production deployment: https://wildhackpvz.vercel.app

Scientific Visualizations

Project Overview

The game is structured as an asymmetric duel:

• the plant side places defensive units on the grid
• the zombie side deploys offensive units from the right edge
• both sides operate on shared resources, timing, and board-state pressure

This repository focuses on three pillars:

• a polished browser-playable PvZ duel
• a configurable balancing workflow through an admin console
• an AI control path that can take over the zombie side in real time

Core Features

• real-time two-sided PvZ-inspired gameplay in the browser
• configurable plant roster including Shooter, Wallnut, Sunflower, Potato Mine, and Bomb
• zombie roster including Walker, Runner, and Brute
• live balance tuning through a dedicated admin panel
• plant upgrading on occupied cells with level caps
• fullscreen demo flow, countdown, overlays, and match restart loop
• optional zombie AI that runs directly in the browser

AI System

The AI path in this project is designed around a browser-deployable Deep Q-Network (DQN) controller for the zombie side.

• the runtime loads assets/models/best_model.browser.json directly in the client
• the exported model uses a 366-dimensional observation vector and 31 discrete actions
• observations encode board occupancy, plant types, normalized health, plant upgrade levels, zombie presence, timer state, resources, and zombie spawn cooldown
• inference ranks Q-values for all candidate actions and executes the highest-scoring valid spawn action under current game constraints

This keeps the deployed experience lightweight while still demonstrating a full trained-policy inference loop inside the game client.

AI Pipeline Reference

Inline PDF preview may not render in every GitHub client. Open the pipeline directly here: AI training pipeline PDF.

Direct PDF link: AI training pipeline PDF

Computer Vision Direction

Computer vision is part of the project direction, but it is intentionally kept outside the core simulation layer.

The current architecture is compatible with a CV-driven control pipeline in which an external perception module can:

• observe a physical setup, player gestures, or board state
• convert those signals into structured game actions
• send those actions through the same interface used by human or AI controllers

This separation is important. It means the game logic, balance systems, and AI controller remain stable while the perception layer can evolve independently. In practice, that makes the project suitable for future work such as camera-based board detection, gesture input, or hybrid physical-digital gameplay demos without requiring a rewrite of the simulation.

Local Development

Start the local dev server:

npm run dev

Then open:

• game: http://localhost:4173
• admin console: http://localhost:4173/admin.html

Running both pages at the same time allows live balance updates to propagate through browser storage and apply immediately to active game tabs.

Controls

Plant player:

• 1 Shooter
• 2 Wall
• 3 Sunflower
• 4 Potato Mine
• 5 Bomb
• W, A, S, D move the plant cursor
• Space places or casts at the cursor
• mouse click places directly on a board cell

Zombie player:

• 8 Walker
• 9 Runner
• 0 Brute
• arrow keys move the zombie cursor
• / deploys at the cursor
• mouse click deploys in the two rightmost columns

Other:

• R restarts the match

Live Balance Console

The admin page is designed for rapid iteration and demo support. It can tune:

• resource economy
• zombie deployment cooldown
• plant and zombie HP, damage, speed, and cost
• mine trigger and explosion values
• bomb explosion values

Our Contributions

• Built the full game loop, balancing workflow, and browser demo experience from scratch.
• Trained and integrated a reinforcement learning agent that can control the zombie side in real time.

Project Structure

.
├── assets/
│   ├── audio/              Runtime sound assets
│   ├── backgrounds/        Battlefield and fullscreen backdrops
│   ├── models/             Browser-deployable AI policy artifacts
│   └── pvz/                Sprite and gameplay art assets
├── docs/
│   ├── experiments/        Non-runtime prototypes and visual experiments
│   ├── figures/            README-ready scientific diagrams
│   ├── notes/              Planning and project notes
│   └── pipeline/           AI pipeline reference documents
├── styles/                 Game and admin stylesheets
├── src/                    Game loop, rendering, audio, config, and AI logic
├── admin.html              Live tuning interface
├── index.html              Main playable entry point
└── plants-vs-zombies-2p.html

Runtime highlights:

• index.html and styles/game.css define the main game surface and presentation.
• src/main.js handles input, UI state, overlays, and AI integration.
• src/game.js manages the simulation loop, rules, combat, and win conditions.
• src/zombie-ai.js builds observations and runs browser-side model inference.
• assets/models/best_model.browser.json stores the exported zombie policy network.
• admin.html, styles/admin.css, and src/admin.js power the balancing interface.
• docs/pipeline/ai_training_pipeline.pdf stores the AI pipeline reference used in the README.

Attribution

• https://github.com/ilovecopy/Plants-vs-Zombies (sprite animation image reference)
• https://sounds.spriters-resource.com/pc_computer/plantsvszombies/asset/394987/ (sound effects)
• https://pixabay.com/sound-effects/search/nuclear%20bomb/ (bomb sound effect)
• Plants vs. Zombies remains the creative inspiration behind this project direction.