Installation Guide

Installation Guide

Get TTT running locally for development or your own deployment.

Just Want to Play?

No installation needed! Just visit https://stevenfarless.github.io/ttt/

This guide is for developers who want to:

• Contribute to the project
• Host their own version
• Test changes locally
• Use a custom Firebase instance

Prerequisites

• Modern web browser - Chrome, Firefox, Safari, or Edge
• Git - For cloning the repository
• (Optional) Code editor - VS Code, Sublime Text, etc.
• (Optional) Local server - For ES6 module support

Note: No build tools, npm, or package managers required! TTT uses vanilla JavaScript.

Quick Setup (5 minutes)

1. Clone the Repository

git clone https://github.com/stevenfarless/ttt.git
cd ttt

2. Choose Your Branch

Pick the version you want:

# Stable production version (recommended)
git checkout main

# Preview upcoming features
git checkout beta

# Test features in development
git checkout alpha

# Experimental prototypes
git checkout experimental

See Branch Strategy for details on each branch.

3. Run Locally

Option A: Direct File Opening (Simplest)

Just double-click index.html or drag it into your browser.

⚠️ Limitation: ES6 modules won't work due to CORS. You'll see Firebase errors in the console.

Option B: Local Server (Recommended)

ES6 modules require a server. Pick one:

Python 3:

python -m http.server 8000

Node.js:

npx http-server

PHP:

php -S localhost:8000

VS Code Live Server Extension:

• Install "Live Server" extension
• Right-click index.html → "Open with Live Server"

Then visit: http://localhost:8000

4. Configure Firebase (For Multiplayer)

⚠️ Important: To actually play multiplayer, you need Firebase credentials.

See the Firebase Setup guide for step-by-step instructions.

Quick version:

1. Create a Firebase project at console.firebase.google.com
2. Enable Realtime Database
3. Copy your config from Project Settings
4. Update utils.js with your credentials

Project Structure

ttt/
├── index.html              # Lobby page
├── game.html               # Game board page
├── style.css               # Game styles (gradients, board)
├── home.css                # Lobby styles
├── multiplayer.js          # Room creation/joining logic
├── game-multiplayer.js     # Game logic & Firebase sync
├── utils.js                # Firebase config & utilities
├── svg-icons.html          # SVG icon definitions
├── README.md               # Project documentation
├── CONTRIBUTING.md         # Contribution guidelines
└── LICENSE                 # GPL-3.0 License

Dependencies

Runtime Dependencies

Zero JavaScript libraries! TTT uses:

• Vanilla JavaScript (ES6+) - Pure JS, no frameworks
• Firebase SDK - Loaded via CDN (not bundled)
• Native APIs - Clipboard API, Session Storage

The Firebase SDK is loaded from CDN in the HTML files:

<script src="https://www.gstatic.com/firebasejs/9.x.x/firebase-app-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/9.x.x/firebase-database-compat.js"></script>

No Build Tools Required

• ❌ No npm install
• ❌ No webpack/vite/parcel
• ❌ No transpilation
• ❌ No minification (for development)
• ✅ Just clone and open!

Testing Your Setup

1. Check the Console

Open DevTools (F12) and check for errors:

Good signs:

[MULTIPLAYER] Script loaded at 2025-11-12T...
[MULTIPLAYER] ✅ DOM elements loaded successfully
[MULTIPLAYER] 🎨 Available emojis: ❌ ⭕ ❤️ ...

Bad signs:

Failed to load module script: CORS error
Firebase is not defined

If you see CORS errors → Use a local server (Option B above)

2. Test Room Creation

1. Click "Create Game"
2. Check console for: [MULTIPLAYER] 🎲 Generated room code: XXXX
3. If you see Firebase errors → Update your Firebase config in utils.js

3. Test Room Joining

Open two browser windows:

• Window 1: Create a game
• Window 2: Join with the room code
• Both should sync in real-time

Troubleshooting

"Failed to load module script" (CORS)

Problem: Opening index.html directly triggers CORS restrictions.

Solution: Use a local server (see Option B above).

"Firebase is not defined"

Problem: Firebase SDK not loading.

Solutions:

1. Check your internet connection (CDN requires internet)
2. Check browser console for CDN loading errors
3. Verify the Firebase SDK script tags in HTML files

"Permission denied" (Firebase)

Problem: Firebase database rules blocking access.

Solution: In Firebase Console → Realtime Database → Rules, set:

{
  "rules": {
    ".read": true,
    ".write": true
  }
}

⚠️ Note: These rules are for development only. See Firebase Setup for production rules.

Styles Not Applying

Problem: Browser cache or missing CSS files.

Solutions:

1. Hard refresh: Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac)
2. Clear browser cache
3. Check that style.css and home.css exist in the project directory

ES6 Modules Not Working

Problem: Browser doesn't support ES6 modules or CORS blocking.

Solutions:

1. Update your browser to the latest version
2. Use a local server instead of opening files directly
3. Check that <script type="module"> is in the HTML files

"Game not found" When Testing Locally

Problem: Using different Firebase instances or configs.

Solution:

1. Make sure both browser windows use the same Firebase config
2. Check that the room code is correct (case-sensitive)
3. Verify Firebase database has the room data (check Firebase Console)

Development Workflow

Making Changes

1. Edit files in your code editor
2. Save changes
3. Refresh browser (F5 or Cmd+R)
4. Check console for errors
5. Test thoroughly (see Contributing Guidelines)

Testing Multiplayer

1. Open two browser windows (or use incognito + regular)
2. Window 1: Create game
3. Window 2: Join with room code
4. Make moves in both windows
5. Verify sync - moves should appear instantly in both windows

Debugging

Console Logging:

TTT has extensive console logging with prefixes:

[MULTIPLAYER] 🎮 Create Game clicked
[MULTIPLAYER] 🎲 Generated room code: AB3X
[MULTIPLAYER] 📤 Creating game with data: {...}

Enable debug mode in multiplayer.js:

const DEBUG = true;  // Set to false to disable logs

Firebase Debugging:

Check Firebase Console → Realtime Database to see live data:

• View room data structure
• Verify moves are being written
• Check turn and winner values

Environment Configuration

Firebase Config

The Firebase configuration is stored in utils.js:

export const firebaseConfig = {
  apiKey: "YOUR_API_KEY",
  authDomain: "YOUR_AUTH_DOMAIN",
  databaseURL: "YOUR_DATABASE_URL",
  projectId: "YOUR_PROJECT_ID",
  storageBucket: "YOUR_STORAGE_BUCKET",
  messagingSenderId: "YOUR_MESSAGING_ID",
  appId: "YOUR_APP_ID"
};

For development:

• Use your own Firebase project (free tier works great)
• Never commit your real credentials to public repos
• Use .gitignore to exclude config files (if you add them)

For contributors:

• The maintainer's Firebase config is in the repo
• This is intentional (public game, read/write access OK)
• For PRs, use the existing config or your own test instance

See Firebase Setup for creating your own Firebase project.

Deployment Options

GitHub Pages (Recommended)

TTT uses GitHub Pages with GitHub Actions for deployment.

To deploy your fork:

1. Fork the repository
2. Enable GitHub Pages in Settings
3. GitHub Actions will auto-deploy on push
4. Visit https://YOUR-USERNAME.github.io/ttt/

See .github/workflows/deploy-gh-pages.yml for the workflow configuration.

Other Hosting Options

TTT works on any static hosting:

• Netlify - Drag and drop the folder
• Vercel - Connect your Git repo
• Firebase Hosting - firebase deploy
• AWS S3 - Upload files to bucket
• Your own server - Copy files to web root

No build step needed—just upload the files!

Next Steps

Start Contributing

See Contributing Guidelines for:

• Code style guidelines
• Pull request process
• Issue labels
• Testing requirements

Learn the Architecture

See Architecture to understand:

• Project structure
• Role-based player system
• Firebase data flow
• ES6 module organization

Set Up Firebase

See Firebase Setup for:

• Creating a Firebase project
• Configuring database rules
• Getting your credentials
• Security best practices

Getting Help

Stuck? Here's where to get help:

• 📖 Check the FAQ
• 🔧 See Troubleshooting
• 💬 Start a GitHub Discussion
• 🐛 Create a GitHub Issue

---

Ready to play or contribute? You're all set! 🎮🚀