Plinko Game - Local Setup Guide

A web-based Plinko gambling game with animated ball drops, Firebase authentication, and persistent user balances.

Prerequisites

Before you begin, make sure you have the following installed:

• Node.js (v14 or higher) - Download here
• npm (comes with Node.js)
• A code editor (VS Code recommended)
• A web browser (Chrome, Firefox, Safari, etc.)

Project Structure

your-project-folder/
├── server.js              # Backend server
├── package.json           # Node.js dependencies
├── .env.example          # Environment variable examples
├── public/               # Frontend files
│   ├── index.html        # Main HTML file
│   ├── script.js         # Game logic and animations
│   ├── style.css         # Styling
│   └── firebase.js       # Firebase configuration
└── data/                 # User balance data (auto-created)
    └── balances.json     # Stored user balances

Installation Steps

1. Install Dependencies

Open your terminal in the project folder and run:

npm install

This will install all required packages:

• express - Web server framework
• cors - Cross-origin resource sharing
• firebase-admin - Firebase authentication (optional)
• dotenv - Environment variable management

2. Start the Server

Run the following command:

node server.js

You should see:

Plinko game server running on http://localhost:3000
Running in development mode without Firebase authentication

3. Open in Browser

Open your web browser and go to:

http://localhost:3000

You should see the Plinko game interface!

How to Use

Playing the Game

1. Login - In development mode, you can use any email/password (authentication is disabled)
2. Place a Bet - Enter an amount in the bet input field
3. Drop Ball - Click the "Drop Ball" button to watch the animation
4. View Results - The ball will land in a slot, and your balance updates accordingly
5. Reset Balance - Click "Reset Balance" to go back to $1000.00

Game Rules

• Starting balance: $1000.00
• Multipliers vary based on slot position (center = low, edges = high)
• The ball randomly drops through pegs to land in a slot
• Your payout = bet amount × slot multiplier
• Balance updates after the ball animation completes

Stopping the Server

To stop the server, press:

Ctrl + C

(On Mac: Cmd + C)

Restarting After Code Changes

If you make changes to the code:

1. Stop the server: Ctrl + C or pkill -9 node
2. Restart the server: node server.js
3. Hard refresh browser: Cmd + Shift + R (Mac) or Ctrl + Shift + R (Windows/Linux)

Troubleshooting

Port Already in Use Error

If you see EADDRINUSE: address already in use :::3000:

Solution 1 - Kill the process:

lsof -i :3000
# Note the PID number, then:
kill -9 [PID]

Solution 2 - Kill all Node processes:

pkill -9 node

Solution 3 - Use a different port: Edit server.js and change:

const PORT = process.env.PORT || 3001;  // Changed from 3000 to 3001

Browser Showing Old Code (Caching Issues)

If your changes aren't showing up:

1. Hard refresh: Cmd + Shift + R (Mac) or Ctrl + Shift + R (Windows/Linux)
2. Clear cache:
   • Open DevTools (F12)
   • Network tab → Check "Disable cache"
   • Keep DevTools open and refresh
3. Clear all site data:
   • DevTools (F12) → Application tab
   • Storage → Clear site data

File Not Found Errors

Make sure you're in the correct directory:

# Check current directory
pwd

# List files - you should see server.js and public/
ls

Optional: Firebase Authentication Setup

If you want to enable real Firebase authentication:

1. Create a Firebase project at Firebase Console
2. Download service account key:
   • Go to Project Settings → Service Accounts
   • Click "Generate new private key"
   • Save as firebase-service-account.json in project root
3. Update Firebase config:
   • Edit public/firebase.js with your Firebase config
4. Restart the server

The app will now use real Firebase authentication instead of dev mode.

Development Mode vs Production Mode

Development Mode (Current)

• No Firebase setup required
• Any email/password works for login
• Perfect for local testing
• Single shared balance for all "users"

Production Mode (With Firebase)

• Real user authentication
• Individual user balances
• Secure token verification
• Requires Firebase project setup

Tips for Development

Using Nodemon (Auto-restart on changes)

Install nodemon globally:

npm install -g nodemon

Run with nodemon:

nodemon server.js

Now the server automatically restarts when you save server files!

Browser DevTools

Press F12 (or Cmd + Option + I on Mac) to open DevTools:

• Console - See JavaScript errors and debug logs
• Network - Check if files are loading correctly
• Sources - Debug JavaScript code
• Application - Clear cache and storage

Common Commands Reference

# Install dependencies
npm install

# Start server
node server.js

# Start with auto-restart
nodemon server.js

# Stop server
Ctrl + C  (or Cmd + C on Mac)

# Kill all Node processes
pkill -9 node

# Check what's using port 3000
lsof -i :3000

# Kill specific process
kill -9 [PID]

Questions or Issues?

If you run into problems:

1. Make sure all dependencies are installed: npm install
2. Check that the server is running: Look for "Plinko game server running" message
3. Verify you're accessing the correct URL: http://localhost:3000
4. Clear browser cache if changes aren't showing up
5. Check the browser console (F12) for JavaScript errors

---

Enjoy playing Plinko!