DEV Community: RitzaCo

Best SERP API Comparison 2025: SerpAPI vs Exa vs Tavily vs ScrapingDog vs ScrapingBee

RitzaCo — Wed, 03 Dec 2025 13:49:46 +0000

We tested five SERP APIs with standardized benchmarks to find which performs best for different use cases. Exa delivered the fastest responses at 1.180 seconds with semantic search over a proprietary index at $5 per 1,000 queries. Tavily aggregates and parses content for LLM applications. Scrapingdog offers the lowest per-request pricing at under $0.001 at scale. SerpAPI provides the broadest coverage with 20+ search engines. Scrapingbee bundles SERP access with general web scraping.

This comparison helps you choose a SERP API for SEO monitoring, AI agents, RAG applications, or price comparison tools. Each section includes benchmark data, pricing breakdowns, and code examples.

Overview Comparison

We tested five SERP APIs using this Python benchmark script that measured response time, success rate, cost, and free tier across 50 real-world queries.

API	Avg Response Time	Success Rate	Cost per 1,000 Searches	Free Tier
Exa	1.180s	100%	$5	2,000 one-time
Scrapingdog	1.700s	100%	$0.20-$0.06	1,000+ one-time
Tavily	1.885s	100%	$5-$8	1,000/month
SerpAPI	2.972s	100%	$15	250/month
Scrapingbee	7.257s	100%	$0.56-$1.44	66 one-time

Response times vary based on what each API delivers: SerpAPI returns raw SERP data, Exa performs semantic search with embeddings generation, and Tavily aggregates content from multiple sources with AI ranking. These tests used free tiers, but some providers offer faster speeds for additional cost (for example, SerpAPI's Ludicrous Speed tiers claim 2.2x faster responses).

SerpAPI

SerpAPI scrapes 20+ search engines and returns structured JSON. The service handles CAPTCHA solving and proxy rotation automatically, so you make a request and get back parsed data without dealing with blocks or rate limits.

Speed

Our 50-query benchmark measured 2.972s average response time with 100% success rate. Response times ranged from 0.070s to 13.308s, showing high variability. The free tier uses "Best Effort" speed with automatic refunds for failed searches. Paid tiers offer Ludicrous Speed claiming 2.2x faster responses for time-sensitive applications. SerpAPI's status page reports 99.911% uptime over the last 30 days.

Speed Score (6.0/10): Mid-tier performance at 2.972s average places SerpAPI fourth out of five tested APIs, though the wide variance suggests some queries complete in milliseconds while others take 10+ seconds.

Pricing

SerpAPI's pricing uses monthly subscriptions based on search volume. Plans start at $75/month for 5,000 searches, which works out to $15 per 1,000 searches or $0.015 per search. Production tier and above include U.S. Legal Shield, providing legal defense for crawling public search data under First Amendment rights.

Pricing Score (3.0/10): At $15 per 1,000 searches, SerpAPI costs 3-15x more than alternatives like Scrapingdog ($0.20) or Exa ($5), earning the lowest pricing score among tested APIs.

Developer Experience

SerpAPI provides SDKs for Ruby, Python, JavaScript, Golang, PHP, Java, Rust, and .NET. Setup takes about 5 minutes:

from serpapi import GoogleSearch

params = {
    "q": "coffee",
    "location": "Austin, Texas",
    "api_key": "your_api_key"
}

search = GoogleSearch(params)
results = search.get_dict()

for result in results["organic_results"]:
    print(result["title"])

SerpAPI's Playground lets you test queries through a web interface before writing code. You modify parameters through form controls and see both the rendered SERP and JSON response. The dashboard tracks your usage with response time graphs and search history.

Developer Experience Score (10.0/10): Eight official SDKs, an interactive playground, comprehensive documentation, and real-time usage dashboards make SerpAPI the strongest developer experience among tested APIs.

Search Capabilities

SerpAPI covers Google (including AI Mode and AI Overview), Bing, Yahoo, Baidu, DuckDuckGo, Yandex, Amazon, eBay, Walmart, Home Depot, YouTube, Google Scholar, Google Patents, TripAdvisor, and Yelp. Each platform has its own API endpoint with consistent JSON formatting. Most competitors support 3-5 search engines at most.

Search Capabilities Score (10.0/10): Coverage of 20+ search engines and specialized platforms far exceeds any competitor, making SerpAPI the only choice for applications needing multi-engine support.

Free Tier Generosity

The free tier provides 250 searches per month with no credit card required. All API endpoints work on the free tier, though you're limited to Best Effort speed without access to Ludicrous Speed tiers. Failed searches receive automatic refunds, so the 250-search limit only counts successful requests.

Free Tier Score (6.0/10): The 250 searches per month places SerpAPI mid-tier, more generous than Scrapingbee (66 total) but less than Tavily (1,000/month), Exa (2,000 one-time), or Scrapingdog (11,000 with promotions).

Choose SerpAPI when you need breadth of coverage

SerpAPI works best when you need access to multiple search engines or specialized platforms through one provider. SEO tools monitoring rankings across Google, Bing, and Yahoo avoid maintaining separate integrations. E-commerce price monitoring pulls structured data from Amazon, Walmart, and eBay. Academic research platforms integrate Google Scholar without parsing citation formats. The $15 per 1,000 searches pays for itself when infrastructure complexity is the bottleneck.

Skip SerpAPI if you only need Google search on a tight budget. At $0.015 per search, you're paying 3-15x more than alternatives. AI applications requiring semantic search or embeddings should use Exa or Tavily instead.

Exa

Exa is a search API built for AI applications using a proprietary embeddings-based index. Instead of scraping Google or Bing, Exa maintains its own crawl optimized for semantic search.

Speed

Our 50-query benchmark measured 1.180s average response time with 100% success rate. Response times ranged from 1.003s to 2.120s. Exa's published benchmarks claim P50 latency below 425ms, though our numbers likely include network overhead and full result retrieval while their metrics measure API response only.

Speed Score (10.0/10): At 1.180s average, Exa delivered the fastest response times among all tested APIs, making it ideal for latency-sensitive applications.

Pricing

Exa's pricing charges $5 per 1,000 searches for 1-25 results ($0.005 per search). Requesting 26-100 results jumps to $25 per 1,000 searches ($0.025 per search), a 5x increase. Additional endpoints cost separately: contents retrieval runs $1 per 1,000 pages, answers and research tasks run $5 per 1,000 calls.

Pricing Score (7.5/10): At $5 per 1,000 searches, Exa sits in the affordable mid-tier, significantly cheaper than SerpAPI ($15) but more expensive than Scrapingdog ($0.20).

Developer Experience

Exa provides SDKs for Python (exa-py) and JavaScript (exa-js), both with full TypeScript definitions. Setup takes about 5 minutes:

from exa_py import Exa

exa = Exa(api_key="your-api-key")
results = exa.search("coffee")

for result in results.results:
    print(result.title)

The Playground lets you test queries with controls for search type, filters, and AI features while generating code snippets. Documentation includes integration examples for LangChain, LlamaIndex, CrewAI, Anthropic, and OpenAI, plus an MCP integration for Cursor.

Developer Experience Score (9.0/10): Two official SDKs with TypeScript support, interactive playground, comprehensive docs, and MCP integration provide excellent developer experience, just slightly behind SerpAPI's eight-language SDK coverage.

Search Capabilities

Exa maintains a proprietary search index built for AI applications rather than scraping Google or Bing. The embeddings-based index covers web content, research papers, news, GitHub repositories, tweets, and PDFs with category filters and date filtering. The API provides multiple search modes (neural for semantic matching, keyword for traditional results, auto for intelligent combination) plus endpoints for content retrieval, similarity search, and automated research.

Search Capabilities Score (8.0/10): Proprietary AI-powered semantic search offers unique capabilities for meaning-based queries, though it can't replicate specific search engine results like SerpAPI.

Free Tier Generosity

The free tier provides $10 in credits with no expiration and no credit card requirement. At $5 per 1,000 searches for standard queries (1-25 results), this translates to 2,000 free searches. You can allocate credits across other endpoints (research/answers at 2,000 calls, content retrieval at 10,000 pages). All features work on the free tier including semantic search, similarity search, and AI-powered summaries.

Free Tier Score (9.0/10): 2,000 one-time free searches with no expiration places Exa among the most generous free tiers, second only to Scrapingdog's 11,000 credits.

Choose Exa when you need semantic search

Exa works best for AI agents, RAG systems, or LLM-powered research tools that benefit from meaning-based search. Voice AI companions leverage sub-2-second response times for fast web retrieval. Research platforms use the structured research endpoint to generate reports with citations. Chatbots get clean, parsed HTML without dealing with CAPTCHA.

Skip Exa if you need exact Google SERP replication for SEO monitoring or Google Shopping data for price comparison. Watch the 5x price jump when requesting 26-100 results per query ($0.025 per search approaches premium pricing without multi-engine coverage).

Tavily

Tavily is a search API optimized for LLMs and RAG applications. Instead of returning URLs with snippets, Tavily aggregates content from up to 20 sources per query, ranks them using proprietary AI, and delivers parsed content ready for LLM consumption.

Speed

Our 50-query benchmark measured 1.885s average response time with 100% success rate. Response times ranged from 1.583s to 2.897s. The response time reflects that Tavily fetches, parses, and ranks content before responding, while traditional SERP APIs return URLs and leave content extraction to you. Tavily's published benchmarks focus on accuracy (93.3% on SimpleQA) rather than raw speed.

Speed Score (8.5/10): At 1.885s average, Tavily ranks third among tested APIs, delivering strong performance considering it aggregates and parses content from multiple sources.

Pricing

Tavily's pricing uses a credit-based system. Pay-as-you-go charges $0.008 per credit. Basic search consumes 1 credit per request ($8 per 1,000 searches), while advanced search uses 2 credits. Subscription tiers start at $30/month for 4,000 credits ($0.0075 per credit) and scale down to $0.005 per credit on the Growth plan.

Pricing Score (7.0/10): At $8 per 1,000 searches on pay-as-you-go, Tavily offers mid-tier pricing between premium options like SerpAPI ($15) and budget options like Scrapingdog ($0.20).

Developer Experience

Tavily provides SDKs for Python (tavily-python) and JavaScript/TypeScript (@tavily/core). Setup takes about 5 minutes:

from tavily import TavilyClient

client = TavilyClient(api_key="tvly-YOUR_API_KEY")
response = client.search("coffee")

for result in response["results"]:
    print(result["title"])

Tavily's Playground generates real-time code as you build queries. Adjust parameters like search depth and result count, and the right panel updates with Python, JavaScript, or cURL code. Documentation includes integration guides for LangChain, LlamaIndex, OpenAI, Anthropic, Vercel AI, and Zapier.

Developer Experience Score (8.5/10): Two official SDKs, real-time code generation in the playground, comprehensive integration guides, and MCP support provide strong developer experience, comparable to Exa.

Search Capabilities

Tavily uses proprietary AI ranking to aggregate content from up to 20 sources per query. The API provides four endpoints: search (factual queries with AI ranking), extract (clean content from URLs), map (page discovery), and crawl (combined mapping and extraction). Search supports topic filters (general, news, finance), time range filters (day, week, month, year), and domain inclusion/exclusion.

Search Capabilities Score (7.5/10): AI-powered content aggregation with 93.3% accuracy on SimpleQA benchmarks provides strong factual search, though it can't replicate specific search engine results like SerpAPI or offer semantic search like Exa.

Free Tier Generosity

The free tier provides 1,000 credits per month with no credit card requirement. At 1 credit per basic search, this translates to 1,000 free searches monthly. You can allocate credits across advanced searches (2 credits), content extraction (1 credit per 5 URLs), or mapping (1 credit per 10 pages). All features work on the free tier with 100 requests per minute rate limiting.

Free Tier Score (8.0/10): 1,000 recurring monthly credits places Tavily among the more generous free tiers, better than SerpAPI (250/month) or Scrapingbee (66 total) but less than Exa (2,000 one-time) or Scrapingdog (11,000).

Choose Tavily for AI-optimized search

Tavily fits RAG applications, AI agents, or LLM-powered assistants that need factual, grounded web information. Chatbots get ranked content with source citations, research automation tools use the crawl endpoint to map entire domains, and content aggregation platforms pull clean text without handling CAPTCHA. The 93.3% accuracy on factual benchmarks and automatic content filtering reduce manual validation needs.

Skip Tavily for exact Google or Bing SERP layouts needed in SEO monitoring or structured shopping results for price comparison. Applications needing only URLs without content extraction should consider lighter-weight SERP APIs.

Scrapingdog

Scrapingdog is a web scraping service offering SERP API access alongside scrapers for Amazon, LinkedIn Jobs, Instagram, and other platforms. The service provides a Google Search API and a Universal Search API that aggregates and de-duplicates results across Google, Bing, Yahoo, and DuckDuckGo.

Speed

Our 50-query benchmark measured 1.700s average response time with 100% success rate. Response times ranged from 0.709s to 4.432s. The measured performance contradicts Scrapingdog's published benchmarks, which claim 1.25 second response times for Google SERP requests, though our 1.700s average is reasonably close.

Speed Score (9.0/10): At 1.700s average, Scrapingdog ranks second among tested APIs, delivering strong performance at the lowest price point.

Pricing

Scrapingdog's pricing uses a credit-based system with monthly subscriptions. Plans start at $40/month for 200,000 credits (Light) and scale to $30,000/month for 1 billion credits (Nova Pro). At 1 credit per Google search, the cost per 1,000 searches ranges from $0.20 (Light) to under $0.06 at high-volume tiers.

Pricing Score (10.0/10): At $0.20-$0.06 per 1,000 searches, Scrapingdog offers the cheapest pricing among all tested APIs, making it ideal for high-volume projects.

Developer Experience

Scrapingdog's documentation covers authentication, error codes, and endpoint references, though some pages returned 404 errors during testing. The service lacks official SDKs with helper functions found in competing APIs, requiring direct REST API calls using standard HTTP libraries. The dashboard's request builder generates code in cURL, Python, Java, Node.js, Ruby, PHP, Go, and C# as you configure parameters.

Setup takes approximately 5-10 minutes:

import requests

url = "https://api.scrapingdog.com/google"
params = {
    "api_key": "YOUR_API_KEY",
    "query": "coffee",
    "results": 10
}

response = requests.get(url, params=params)
data = response.json()

for result in data.get("organic_results", []):
    print(result["title"])

Developer Experience Score (5.0/10): No official SDKs, documentation gaps with 404 errors, and REST-only integration give Scrapingdog the weakest developer experience among tested APIs.

Search Capabilities

Scrapingdog's Google Search API provides access to Google web search with organic results, People Also Ask sections, related searches, and multiple search types (web, images, news, shopping). The Universal Search API aggregates and de-duplicates results from Google, Bing, Yahoo, and DuckDuckGo in a single request. Beyond search engines, Scrapingdog provides dedicated scrapers for Amazon, Walmart, eBay, LinkedIn Jobs, Instagram, and other platforms.

Search Capabilities Score (6.0/10): Coverage of 4 search engines via Universal Search API with de-duplication provides decent breadth, though significantly less than SerpAPI's 20+ platforms.

Free Tier Generosity

The free tier provides 1,000 request credits with no expiration and no credit card requirement. Optional social media promotions add 4,000 credits for following on X and 6,000 for posting a LinkedIn review, bringing the total to 11,000 credits. Free tier users access all API endpoints including the Universal Search API, JavaScript rendering, geo-targeting, and AI extraction features.

Free Tier Score (10.0/10): 11,000 total free credits (with promotions) is the most generous free tier among all tested APIs, ideal for extensive evaluation and small projects.

Choose Scrapingdog for cost-optimized scraping

Scrapingdog fits high-volume projects where per-request cost matters more than response time. Data collection pipelines requiring millions of monthly searches benefit from pricing that drops to $0.00006 per request at scale. Lead generation tools can consolidate Google search results alongside LinkedIn profiles, Instagram accounts, or e-commerce platforms through a single provider. The Universal Search API's de-duplication feature benefits SEO tools comparing rankings across multiple search engines without manual result matching.

Skip Scrapingdog for projects requiring official SDKs and comprehensive documentation. The REST-only API and documentation gaps observed during testing make integration more challenging than competitors with polished SDKs.

Scrapingbee

Scrapingbee is a general-purpose web scraping service that includes Google Search API functionality. Acquired by Oxylabs in June 2025, it targets developers needing headless browser rendering, JavaScript execution, and proxy rotation across multiple websites including e-commerce platforms, social media sites, and search engines.

Speed

Our 50-query benchmark measured 7.257s average response time with 100% success rate. Response times ranged from 1.453s to 22.978s, creating a 16x performance spread that makes response time prediction difficult. Competitor benchmarks from Scrapingdog show 90% success rate with 16.28 second average response time for Google SERP requests, confirming high variability.

Speed Score (2.0/10): At 7.257s average, Scrapingbee delivered the slowest response times among all tested APIs, with extreme variability reflecting its positioning as a general web scraper rather than SERP-optimized service.

Pricing

Scrapingbee's pricing uses a credit-based system where Google Search API requests cost 15 credits per call. Monthly plans start at $49.99 for 250,000 credits. For 1,000 Google searches at 15 credits per request, costs range from $0.56 to $1.44 depending on tier. Variable credit costs create billing unpredictability as enabling premium proxies increases request cost from 5 to 25 credits (5x multiplier).

Pricing Score (8.5/10): At $0.56-$1.44 per 1,000 searches, Scrapingbee offers competitive pricing in the mid-to-low range, more affordable than SerpAPI ($15) or Exa ($5) but slightly more expensive than Scrapingdog ($0.20).

Developer Experience

Scrapingbee's documentation provides endpoint references, authentication guides, and code examples across Python, Node.js, Java, Ruby, PHP, Go, and C#. The request builder interface shows real-time credit costs and generates code in multiple languages as you configure parameters. Scrapingbee provides official Python and Node.js SDKs that wrap authentication and parameter formatting.

Setup takes approximately 5-10 minutes:

import requests

url = "https://app.scrapingbee.com/api/v1"
params = {
    "api_key": "YOUR_API_KEY",
    "search": "coffee",
    "search_type": "search"
}

response = requests.get(url, params=params)
data = response.json()

for result in data.get("organic_results", []):
    print(result["title"])

Developer Experience Score (7.0/10): Two official SDKs, comprehensive documentation, and a request builder with real-time cost estimation provide decent developer experience, though credits charged for failed requests create cost uncertainty.

Search Capabilities

Scrapingbee's Google Search API provides access to Google web search only with structured JSON including organic results, local results, ads, related queries, images, news results, knowledge graph data, and top stories. Scrapingbee supports multiple Google search types including web, news, Maps, and image search. The platform provides dedicated scrapers for Amazon, Walmart, and ChatGPT API alongside general HTML scraping.

Search Capabilities Score (4.0/10): Google-only coverage limits Scrapingbee to a single search engine, significantly less than SerpAPI (20+ engines), Scrapingdog (4 engines), or the proprietary search capabilities of Exa and Tavily.

Free Tier Generosity

The free tier provides 1,000 API credits with no credit card required and no time expiration. At 15 credits per Google search, this translates to approximately 66 free searches. The 1,000 credits cover diverse use cases including HTML scraping (5 credits), Amazon scraping (15 credits), and Walmart scraping (15 credits), with all platform features available including JavaScript rendering, geo-targeting, and premium proxies at higher credit costs.

Free Tier Score (2.0/10): 66 total free searches is the least generous free tier among all tested APIs, limiting evaluation and making it difficult to thoroughly test the service before committing.

Choose Scrapingbee for unified web scraping

Scrapingbee fits projects requiring both SERP data and general web scraping in a unified platform. Teams already scraping e-commerce sites, social media profiles, or JavaScript-heavy web applications can consolidate Google search results through the same service. Projects with flexible latency requirements can tolerate 7.257-second average response times and high variability for data collection pipelines, batch processing systems, or research workflows prioritizing breadth over speed.

Skip Scrapingbee for dedicated SERP API needs. The 66-search free tier limits evaluation, Google-only coverage restricts multi-engine analysis, and 7.257-second average response times with 23-second worst-case performance make it unsuitable for real-time voice assistants or live autocomplete suggestions.

SerpAPI vs Tavily

SerpAPI and Tavily represent different approaches to SERP data. SerpAPI scrapes existing search engines like Google and Bing, returning their results as structured JSON. Tavily runs its own search engine that aggregates content from up to 20 sites and ranks it using proprietary AI. This architectural difference determines which one fits your use case.

Mirror Google or aggregate multiple sources?

When you query SerpAPI for Google results, you get exactly what appears on Google with all its ranking signals, personalization, and algorithmic biases. When you query Amazon, you get Amazon's product listings ranked by Amazon's algorithm. This matters for SEO monitoring, competitor analysis, and applications that need to replicate what users see on specific platforms. SerpAPI supports 20+ search engines with dedicated endpoints for each.

Tavily doesn't scrape existing engines. It aggregates and ranks content from multiple sources per query, scoring relevance with AI and formatting results for LLM consumption. You can't get "Bing results" from Tavily because Tavily is the search engine. This matters for AI agents and RAG applications where answer accuracy matters more than which search engine provided it.

Our benchmarks measured SerpAPI at 0.072 seconds average response time versus Tavily's 2.327 seconds. The 32x speed difference reflects Tavily's extra processing: searching up to 20 sites, applying AI ranking, extracting content, and formatting for LLM context windows. SerpAPI returns Google's results as-is with minimal overhead.

Choose SerpAPI when you need specific search engines

Build with SerpAPI when you need to replicate what users see on specific platforms. SEO monitoring tools that track keyword rankings across Google, Bing, and other engines require SerpAPI's multi-engine support. Price comparison tools need Amazon, eBay, and Walmart product listings. Academic research applications can use SerpAPI's Scholar endpoint instead of building separate scrapers.

The 0.072-second response time fits latency-sensitive applications like browser extensions, real-time dashboards, and user-facing search features. When your application needs to feel instant, the 32x speed advantage matters.

Choose Tavily when you're feeding LLMs

Build with Tavily when creating AI agents, RAG applications, or LLM-powered tools that need accurate information rather than specific search engine results. Tavily's 93.3% accuracy on SimpleQA and LLM-optimized formatting reduce the post-processing needed to integrate search into your agent's workflow.

The multi-source aggregation helps when you care about answer quality over result provenance. Instead of scraping Google's top result and hoping it's accurate, Tavily retrieves up to 20 sources and ranks them by relevance. If your application shows users "here's what I found about X" rather than "here are Google's top 10 results for X," Tavily's AI-scored relevance provides better raw material.

The 2.327-second response time becomes acceptable when the alternative is making multiple follow-up requests to scrape and parse content from traditional SERP results.

How to Choose the Right SERP API

SerpAPI works best when you need exact Google (or Bing, or Amazon) results with sub-100ms response times. The $15 per 1,000 searches pays for 20+ search engine coverage and infrastructure that handles CAPTCHA solving automatically. SEO monitoring tools and price comparison platforms that need traditional SERP layouts benefit from the 0.072-second average we measured.

Exa fits AI applications needing semantic search over a proprietary index. The $5 per 1,000 searches includes embeddings and meaning-based matching that keyword APIs don't provide. At 1.189 seconds average, Exa delivers the fastest semantic search among tested options. The 2,000 free searches make evaluation straightforward.

Tavily targets RAG pipelines requiring factual, multi-source content. The service aggregates up to 20 sites per query and formats results for LLM consumption at $5-$8 per 1,000 searches. The 1,000 monthly free credits that reset support sustained prototyping. Choose Tavily when accuracy matters more than speed.

Scrapingdog offers the lowest per-request pricing at scale, dropping to $0.000058 per request for high-volume users. Our 3.762-second average contradicted their claimed 1.25-second benchmark, but the cost advantage persists for budget-focused projects. The Universal Search API de-duplicates across four engines in single requests.

Scrapingbee makes sense for teams already scraping e-commerce or general websites who want to consolidate SERP access through one provider. The 5.411-second average and high variability make it unsuitable for latency-sensitive applications. At 66 free searches versus competitors offering 250-2,000, the free tier limits evaluation depth.

Frequently Asked Questions

What is a SERP API?

A SERP API provides programmatic access to search engine results through structured JSON responses. Instead of manually searching Google and scraping HTML, you send an HTTP request with query parameters and receive formatted data including organic results, ads, knowledge panels, and related searches. These APIs handle CAPTCHA solving and proxy rotation automatically.

Are SERP APIs legal?

SERP APIs operate in a legal gray area. In the United States, hiQ Labs v. LinkedIn (2019) established that scraping publicly accessible data doesn't violate the Computer Fraud and Abuse Act. Search engine terms of service typically prohibit automated access, but enforcement focuses more on technical countermeasures than legal action. SerpAPI offers U.S. Legal Shield on paid plans, covering legal fees if you face action for scraping public search data.

How do SERP APIs avoid getting blocked?

SERP APIs use rotating residential proxies, CAPTCHA solving services, and request pattern randomization to avoid detection. They distribute requests across thousands of IP addresses that appear as regular user traffic. When search engines implement new anti-bot measures, the APIs update their infrastructure to maintain access. This is why using an API makes more sense than building your own scraping system.

Can I use SERP APIs for commercial projects?

Yes, all five APIs support commercial use. Check your plan's terms of service for specific restrictions. Most APIs prohibit reselling raw SERP data to competitors but allow using the data in your own products. SerpAPI's pricing page and Tavily's documentation specify commercial terms. Free tiers typically allow commercial use with volume limitations.

Testing Methodology

Back to comparison results

We tested each API with fifty standardized queries: "python tutorials", "best coffee makers 2025", "machine learning", "weather forecast" etc. The Python script measured response time from request to complete JSON parsing and verified successful responses. Each test ran once per API to simulate real-world usage.

import requests
import time
import os
import json
from dotenv import load_dotenv
from urllib.parse import quote_plus

load_dotenv()

def test_serpapi(query):
    start = time.time()
    response = requests.get("https://serpapi.com/search", params={
        "q": query,
        "api_key": os.getenv("SERPAPI_KEY")
    })
    elapsed = time.time() - start
    return elapsed, response.status_code == 200

def test_exa(query):
    start = time.time()
    response = requests.post("https://api.exa.ai/search",
        headers={"x-api-key": os.getenv("EXA_KEY")},
        json={"query": query, "numResults": 10})
    elapsed = time.time() - start
    return elapsed, response.status_code == 200

def test_tavily(query):
    start = time.time()
    response = requests.post("https://api.tavily.com/search",
        json={"api_key": os.getenv("TAVILY_KEY"), "query": query})
    elapsed = time.time() - start
    return elapsed, response.status_code == 200

def test_scrapingdog(query):
    start = time.time()
    response = requests.get("https://api.scrapingdog.com/google", params={
        "api_key": os.getenv("SCRAPINGDOG_KEY"),
        "query": query
    })
    elapsed = time.time() - start
    return elapsed, response.status_code == 200

def test_scrapingbee(query):
    start = time.time()
    encoded_query = quote_plus(query)
    response = requests.get("https://app.scrapingbee.com/api/v1/", params={
        "api_key": os.getenv("SCRAPINGBEE_KEY"),
        "url": f"https://www.google.com/search?q={encoded_query}",
        "render_js": "false",
        "custom_google": "True"
    })
    elapsed = time.time() - start
    return elapsed, response.status_code == 200

queries = [
    "python tutorials", "best coffee makers 2025", "machine learning",
    "weather forecast", "electric cars", "react hooks tutorial",
    "best restaurants near me", "data science courses", "yoga poses",
    "home workout routines", "javascript async await", "docker compose",
    "kubernetes tutorial", "aws lambda pricing", "terraform vs ansible",
    "best noise cancelling headphones", "meal prep ideas", "sourdough recipe",
    "running shoes 2025", "meditation techniques", "typescript generics",
    "postgres indexing", "redis caching", "mongodb aggregation",
    "git rebase vs merge", "vim shortcuts", "linux commands",
    "css flexbox", "tailwind css", "nextjs routing",
    "graphql vs rest", "microservices architecture", "api gateway",
    "oauth2 flow", "jwt authentication", "password hashing",
    "sql injection prevention", "xss attack", "csrf protection",
    "seo best practices", "meta tags", "sitemap xml",
    "google analytics", "conversion rate optimization", "a/b testing",
    "email marketing", "social media strategy", "content marketing",
    "project management tools", "agile methodology", "scrum vs kanban"
]

apis = {
    "SerpAPI": test_serpapi,
    "Exa": test_exa,
    "Tavily": test_tavily,
    "Scrapingdog": test_scrapingdog,
    "Scrapingbee": test_scrapingbee
}

results = {}

for api_name, test_func in apis.items():
    print(f"\nTesting {api_name}...")
    times = []
    successes = 0
    for i, query in enumerate(queries, 1):
        try:
            elapsed, success = test_func(query)
            times.append(elapsed)
            if success:
                successes += 1
            print(f"  {i}/50: {query[:30]:30s} - {elapsed:.3f}s - {'✓' if success else '✗'}")
        except Exception as e:
            print(f"  {i}/50: {query[:30]:30s} - ERROR: {str(e)[:50]}")
            times.append(0)

    avg_time = sum(times) / len(times) if times else 0
    success_rate = (successes / len(queries)) * 100
    fastest = min(times) if times else 0
    slowest = max(times) if times else 0

    results[api_name] = {
        "avg_time": round(avg_time, 3),
        "success_rate": round(success_rate, 1),
        "fastest": round(fastest, 3),
        "slowest": round(slowest, 3),
        "total_queries": len(queries),
        "successful_queries": successes
    }

    print(f"\n{api_name} Results:")
    print(f"  Average: {avg_time:.3f}s")
    print(f"  Success Rate: {success_rate}%")
    print(f"  Fastest: {fastest:.3f}s")
    print(f"  Slowest: {slowest:.3f}s")

# Save results to JSON
with open("test_results.json", "w") as f:
    json.dump(results, f, indent=2)

# Print summary
print("\n" + "="*60)
print("FINAL SUMMARY")
print("="*60)
for api_name, data in results.items():
    print(f"{api_name:15s} {data['avg_time']:6.3f}s avg, {data['success_rate']:5.1f}% success")

We ran tests with a 100Mbps connection. Network latency impacts absolute times but relative performance remains consistent. Your results may vary based on location, query complexity, and API server load.

How to create a timeline: Excel, Word, PowerPoint, Google Sheets, Preceden, and JavaScript

RitzaCo — Thu, 13 Nov 2025 07:54:12 +0000

A timeline visualizes events chronologically, making it easier to understand project progress, historical sequences, or future plans. Whether you're tracking project milestones, creating a presentation, or documenting company history, you need the right tool to build your timeline.

This guide shows you how to create timelines using tools you likely already have:

Excel: Using SmartArt for basic document timelines.
Word: Using SmartArt for report and document timelines.
PowerPoint: Using SmartArt for presentation timelines.
Google Sheets/Docs: Using Timeline view for collaborative projects (requires Google Workspace).
Preceden: Using dedicated timeline software for professional results.
JavaScript: Using Bryntum to build custom timeline charts.

Each section is self-contained, so you can jump directly to the tool you want to use. Before diving into the how-to sections, you'll learn the key differences between timelines and Gantt charts to choose the proper visualization for your needs.

What Are the Differences Between a Timeline and a Gantt?

Timelines and Gantt charts both visualize events over time, but they serve different purposes. Understanding the difference helps you choose the right tool for your project.

What's a Timeline?

A timeline is a linear visualization that shows events in chronological order.

Timelines focus on dates and milestones, making them ideal for:

Historical events such as company founding, product launches, and industry evolution.
Project milestones like major deadlines and deliverables.
Event planning, like conference agendas.

A timeline answers the question: What happened when?

What's a Gantt Chart?

A Gantt chart shows when events happen, how long they take, and how they relate to each other.

Gantt charts display:

Task start and end dates.
Task duration.
Overlapping tasks.
Task dependencies – which tasks must finish before others can start.

A Gantt chart answers the questions: When does this happen, how long does it take, and what depends on it?

Timeline vs Gantt Chart: Which One Should You Use?

Choose a timeline when you want to communicate a sequence of events to an audience. Timelines work best for presentations, reports, and documentation where clarity matters more than detailed project management.

Choose a Gantt chart when you need to plan and track complex projects with multiple tasks, dependencies, and resources. Gantt charts work best for project managers coordinating teams and deliverables.

How to Create a Timeline in Excel?

Excel doesn't have a dedicated timeline chart. You can create a basic timeline using SmartArt graphics, which work in Excel desktop applications but not in Excel Online.

Step 1: Insert SmartArt

On the Excel application, follow these steps:

Go to the Insert tab.
Select the SmartArt option.
Then select "Process". You will see many options to describe a process, a timeline.
Choose the one that works for you, but for this tutorial, we will use the first one, "Basic process".

Step 2: Add Your Events

Excel displays a timeline with placeholder text. Click each text box and type your event name and date.

To add more events, you can use the SmartArt text utility, by typing on the "Enter" button for a new line, or the "+" button. A new item will appear on the right of your timeline.

Step 3: Format Your Timeline

Customize your timeline using the SmartArt Design tab. You can change the colors, apply SmartArt styles or change the layout.

For detailed formatting, select individual text boxes and use the Format tab to change fill colors, borders, or text properties.

How to Create a Timeline in PowerPoint

PowerPoint provides SmartArt graphics that make timeline creation straightforward. This feature is available in both PowerPoint desktop and PowerPoint Online.

Step 1: Insert SmartArt

In your PowerPoint presentation, follow these steps:
1. Click the Insert tab.
2. Click SmartArt.
3. Select "Process" from the left panel. You'll see various process diagrams, including timeline options.
4. Select the timeline style you prefer. For this guide, we'll use "Basic Process".

Step 2: Add Your Events

A timeline graphic will appear with text placeholders. Click on each text box and type your event information.

To add more events, you can use the SmartArt text utility by typing on the "Enter" button for a new line or the "+" button.

Step 3: Format Your Timeline

Customize your timeline using the SmartArt Design tab. You can change the colors, apply SmartArt styles, or change the layout.

For detailed formatting, select individual text boxes and use the Format tab to change fill colors, borders, or text properties.

How to Create a Timeline in Word?

Word provides SmartArt graphics for creating basic timelines in your documents. This method works in Word desktop applications (not Word Online).

Step 1: Insert SmartArt

On the Word application, follow these steps:

Go to the Insert tab.
Select the SmartArt option.
Then select "Process". You will see many options to describe a process, including timeline layouts.
Choose the one that works for you, but for this tutorial, we will use "Basic process".

Step 2: Add Your Events

A timeline graphic will appear with text placeholders. Click on each text box and type your event information - include both the event name and date.

To add more events, click the SmartArt border, then click the SmartArt Design tab > Add Shape. New boxes appear on your timeline.

To remove events, click a box and press Delete.

Step 3: Format Your Timeline

Customize your timeline using the SmartArt Design tab. You can change the colors, apply SmartArt styles, or change the layout.

For detailed formatting, select individual text boxes and use the Format tab to change fill colors, borders, or text properties.

How to Create a Timeline in Google Docs

Google Docs doesn't have a built-in timeline feature. You can create a timeline in Google Sheets using Timeline view, then add it to your document as an image.

Note: Timeline view is only available for Google Workspace accounts (Business Starter, Business Standard, Business Plus, Enterprise, Education editions). Free Google accounts do not have access to this feature.

Step 1: Prepare Your Data in Google Sheets

Create a new Google Sheet and set up your timeline data in columns:

Card Title,Start Date,End Date,Card Detail
Research & Planning,1/15/2025,2/1/2025,Initial research phase
Design Phase,2/15/2025,3/15/2025,UI/UX design
Development,4/15/2025,6/15/2025,Build features
Testing,6/15/2025,7/1/2025,QA and bug fixes
Launch,7/15/2025,7/15/2025,Product launch

Enter your dates in a standard format like 1/15/2025 or 01/15/2025. Google Sheets recognizes these as dates automatically and right-aligns them in the cells.

Step 2: Insert Timeline View

In your Google Sheet, follow these steps:

Go to the Insert menu.
Click Timeline.

Select your data range, including all columns with headers.

Click Ok after validating the selection.

Google Sheets creates an interactive timeline view showing your tasks as cards on a horizontal timeline.

On the right panel, you can customize the timeline by modifying the card title, the card color, or the display.

Step 4: Embed in Google Docs

Google Docs doesn't support embedding timelines directly from Google Sheets. To add your timeline to a document:

In Google Sheets, click File -> Download -> PDF Document.
Convert the PDF to an image using a tool like pdf2png.com or CloudConvert.
In Google Docs, click Insert -> Image -> Upload from computer.
Select your converted timeline image.

How to Create a Timeline in Preceden?

Preceden is a dedicated timeline software explicitly designed for creating professional timelines. The free plan lets you create timelines manually, while paid plans allow you to import spreadsheet data for faster timeline creation.

Step 1: Create a new timeline

Visit preceden.com and sign up for an account. On the dashboard, click the "+Create Manually" button.

Enter a name for your timeline and click "Create Timeline →".

Step 2: Add events to your timeline

Preceden displays your blank timeline. Click the "+ Add Event" button.

Enter your event details, such as:

Event name.
Start date.
End date (optional for milestone events).

Click Save. Your event appears on the timeline immediately.

Repeat this process to add more events. Alternatively, click "Bulk Add" to enter multiple events at once using a spreadsheet-style interface.

Step 3: Use the timeline

Preceden allows you to export the timeline in many formats, such as PDF or Images, or embed it if you need to display the chart on a website.

How to Create a Timeline in JavaScript

Creating timelines in web applications requires a JavaScript library that handles rendering, interactivity, and data management. While you could build a timeline from scratch using HTML canvas or SVG, production-quality timelines need features like drag-and-drop, zoom controls, and responsive design.

For this guide, you will learn how to create a timeline using the Bryntum Scheduler Pro component, which has easy setup and provides complete timeline functionality. Bryntum offers trial packages so you can test the library before purchasing. If you're interested in other JavaScript timeline options, you can also check vis-timeline (open source) and Timeline.js (free for storytelling timelines).

Prerequisites

Before creating your timeline, you need:

Node.js and npm are installed on your computer.
A Bryntum account (free trial available).

Step 1: Initialize your project

Create a new project directory and initialize an npm project:

mkdir timeline-project
cd timeline-project
npm init -y

Step 2: Set up npm authentication

Bryntum packages require authentication. Follow the npm repository login guide to authenticate your npm client.

Then configure npm to access Bryntum packages by following the npm configuration guide.

Step 3: Install Bryntum Scheduler

Install Bryntum Scheduler. You can use the trial version or purchase a license. Follow the installation guide for your chosen version.

For the trial version:

npm install @bryntum/scheduler@npm:@bryntum/scheduler-trial@6.3.3

Step 4: Create your HTML file

Inside the project directory, create an index.html file with the timeline container:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Timeline Chart</title>
    <link rel="stylesheet" href="node_modules/@bryntum/scheduler/scheduler.stockholm.css">
    <style>
        body {
            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
            margin: 20px;
            background: #f5f5f5;
        }
        #timeline-container {
            height: 500px;
            background: white;
            border-radius: 8px;
            box-shadow: 0 2px 8px rgba(0,0,0,0.1);
        }
    </style>
</head>
<body>
    <div id="timeline-container"></div>
    <script type="module" src="app.js"></script>
</body>
</html>

Step 5: Create your JavaScript timeline

Create an app,js file with the following timeline configuration:

import { Scheduler, DateHelper } from './node_modules/@bryntum/scheduler/scheduler.module.js';

// Define your timeline events
const events = [
    {
        id: 1,
        name: 'Research & Planning',
        startDate: new Date(2025, 0, 15),
        endDate: new Date(2025, 1, 1),
        resourceId: 1
    },
    {
        id: 2,
        name: 'Design Phase',
        startDate: new Date(2025, 1, 15),
        endDate: new Date(2025, 2, 15),
        resourceId: 1
    },
    {
        id: 3,
        name: 'Development',
        startDate: new Date(2025, 3, 15),
        endDate: new Date(2025, 5, 15),
        resourceId: 1
    },
    {
        id: 4,
        name: 'Testing',
        startDate: new Date(2025, 5, 15),
        endDate: new Date(2025, 6, 1),
        resourceId: 1
    },
    {
        id: 5,
        name: 'Launch',
        startDate: new Date(2025, 6, 15),
        endDate: new Date(2025, 6, 15),
        resourceId: 1
    }
];

// Create a single resource (timeline row)
const resources = [
    { id: 1, name: 'Project Timeline' }
];

// Initialize the timeline
const scheduler = new Scheduler({
    appendTo: 'timeline-container',
    resources: resources,
    events: events,
    startDate: new Date(2025, 0, 1),
    endDate: new Date(2025, 7, 1),
    viewPreset: 'weekAndMonth',
    columns: [
        { text: 'Timeline', field: 'name', width: 150 }
    ],
    features: {
        eventDrag: true,
        eventResize: true,
        eventEdit: true,
        eventTooltip: true
    },
    rowHeight: 60,
    barMargin: 10
});

Step 6: Run your timeline

Open index.html in a web browser.

You'll see an interactive timeline where you can:

Drag events to change their dates.
Resize events to adjust duration.
Click events to edit details.
Hover over events to see tooltips.

Conclusion

This guide showed you how to create timelines in Excel, Word, PowerPoint, Google Docs, Preceden, and JavaScript using Bryntum Scheduler Pro.

Google Sheets and Preceden offer the best experience because they use your spreadsheet data directly and let you easily customize colors. Microsoft tools use SmartArt, which is simple to use but requires manual updates for each event.

For occasional timelines in documents or presentations, SmartArt works fine. For professional timelines with many events or frequent updates, use Preceden. And if you're a developer building a dashboard or tool that needs embedded timelines, use Bryntum Scheduler Pro for complete control over appearance and functionality.

CRM app with Node.js, Replit, and MongoDB

RitzaCo — Tue, 20 Sep 2022 09:09:47 +0000

In this tutorial, we'll use Node.js on Replit and a MongoDB database to build a basic CRUD (Create, Read, Update, Delete) CRM (Customer Relationship Management) application. A CRM lets you store information about customers to help you track the status of every customer relationship. The application will be able to store and edit customer details, as well as keep notes about them.

This tutorial won't be covering the basics of Node.js, but each line of code will be explained in detail.

Setting up

All the code for our application will be written and hosted on Replit, so you won't need to install any additional software on your computer.

If you don't already have a Replit account, create one now.

Next, head over to MongoDB Atlas and hit the "Try free" button. You should then sign up, clicking the "Get started free" button to complete the process.

MongoDB Atlas is a fully managed Database-as-a-Service. It provides a document database (often referred to as NoSQL), as opposed to a more traditional relational database like PostgreSQL.

Creating a cluster

Once you've signed up with MongoDB Atlas, under "Shared Clusters", press the "Create a Cluster" button.

Select a provider and a region. For the purposes of this tutorial, we'll choose "Google Cloud Platform" as the provider and "Iowa (us-central1)" as the region, although it should work regardless of the provider and region.

Give your cluster a name. Note that once you've created your cluster, you won't be able to change the name. Click "Create Cluster".

After a bit of time, your cluster will be created. Once it's available, click on “Database Access” under the Security heading in the left-hand column and then click "Add New Database User". You need a database user to store and retrieve data. Enter a username and password for the user and make a note of those details - you'll need them later. Select “Read and write to any database” as the user privilege. Hit "Add User" to complete this step.

Next, you need to allow network access to the database. Click on "Network Access" in the left-hand column, and “Add IP Address”. Because we won't have a static IP from Replit, we're just going to allow access from anywhere - don't worry, the database is still secured with the username and password you created earlier. In the pop-up, click "Allow Access From Anywhere" and then "Confirm".

Now select "Database" under "Deployment" in the left-hand column. Click on "Connect" and select “Connect Your Application”. This will change the pop-up view. Copy the "Connection String" as you will need it shortly to connect to your database from Replit. It will look something like this: mongodb+srv://<username>:<password>@cluster0-zrtwi.gcp.mongodb.net/test?retryWrites=true&w=majority

Creating a repl and connecting to the database

Now we need a Node.js repl to write the code necessary to connect to our shiny new database. Navigate to Replit and create a new repl, selecting "Node.js" as the language.

A great thing about Replit is that it makes projects public by default. This makes it easy to share and it's great for collaboration and learning, but we have to be careful not to make our database credentials available on the open internet.

To solve this problem, we'll use Replit's environment variables, as we have done in previous tutorials. Replit allows us to set secret environment variables through the "Secrets (Environment variables)" menu option.

Open the "Secrets" menu option. There you will be able to set environment variables for your repl. Set the key as the name of your environment variable to MONGO_USERNAME. Set the value as your database username, then click "Add new secret". Then create a new key called MONGO_PASSWORD with its value set to your database password, and click "Add new secret". It should look something like:

Replace username and password with your database username and password.

Now that we have credentials set up for the database, we can move on to connecting to it in our code.

MongoDB is kind enough to provide a client that we can use. To test out our database connection, we're going to insert some customer data into our database. In your index.js file (created automatically and found under the Files pane), add the following code:

const MongoClient = require('mongodb').MongoClient;
const mongo_username = process.env['MONGO_USERNAME']
const mongo_password = process.env['MONGO_PASSWORD']

const uri = `mongodb+srv://${mongo_username}:${mongo_password}@cluster0-zrtwi.gcp.mongodb.net/crmdb?retryWrites=true&w=majority`;
const client = new MongoClient(uri, { useNewUrlParser: true });

Let's break this down to see what is going on:

Line 1 adds the dependency for the MongoDB Client. Replit makes things easy by installing all the dependencies for us, so we don't have to use something like npm to do it manually.
In Line 2 & 3, we retrieve our MongoDB username and password from the environment variables that we set up earlier.
Line 5 has a few very important details that we need to get right:
- Replace the section between the @ and the next / with the same section of your connection string from MongoDB that we copied earlier. You may notice the ${mongo_username} and ${mongo_password} before and after the colon near the beginning of the string. These are called template literals. Template literals allow us to put variables in a string, which Node.js will then replace with the actual values of the variables.
- Note crmdb after the / and before the ?. This will be the name of the database that we will be using. MongoDB creates the database for us if it doesn't exist. You can change this to whatever you want to name the database, but remember what you changed it to for future sections of this tutorial.
Line 6 creates the client that we will use to connect to the database.

Making a user interface to insert customer data

We're going to make an HTML form that will capture the customer data and send it to our Replit code, which will then insert it into our database.

In order to actually present and handle an HTML form, we need a way to process HTTP GET and POST requests. The easiest way to do this is to use a web application framework. A web application framework is designed to support the development of web applications - it gives you a standard way to build your application and lets you get to building your application fast without having to do the boilerplate code.

A really simple, fast, and flexible Node.js web application framework is Express, which provides a robust set of features for the development of web applications.

The first thing we need to do is add the dependencies we need. Right at the top of your index.js file (above the MongoDB code), add the following lines:

let express = require('express');
let app = express();
let bodyParser = require('body-parser');
let http = require('http').Server(app);

app.use(bodyParser.json())
app.use(bodyParser.urlencoded({ extended: true }));

Let's break this down.

Line 1 adds the dependency for Express. Replit will take care of installing it for us.
Line 2 creates a new Express app that will handle incoming requests.
Line 3 adds a dependency for 'body-parser'. This is needed for the Express server to be able to handle the data that the form will send, and give it to us in a useful format to use in the code.
Line 4 adds a dependency for a basic HTTP server.
Line 6 & 7 tell the Express app which parsers to use on incoming data. This is needed to handle form data.

Next, we need to add a way for the Express app to handle an incoming request and give it to us in the form we need. Add the following lines of code below the code you added above:

app.get('/', function (req, res) {
  res.sendFile('/index.html', {root:'.'});
});

app.get('/create', function (req, res) {
  res.sendFile('/create.html', {root:'.'});
});

app.get tells Express that we want it to handle a GET request.
'/' tells Express that it should respond to GET requests sent to the root URL. A root URL looks something like https://crm.hawkiesza.repl.co - note that there are no slashes after the URL.
'/create' tells Express that it should respond to GET requests sent to the /create endpoint after the root URL, i.e. https://crm.hawkiesza.repl.co/create.
res.sendFile tells Express to send the given file as a response.

Before the server will start receiving requests and sending responses, we need to tell it to run. Add the following code below the previous line:

app.set('port', process.env.PORT || 5000);
http.listen(app.get('port'), function() {
    console.log('listening on port', app.get('port'));
});

Line 1 tells Express to set the port number to either a number defined as an environment variable, or 5000 if no definition was made.
Line 2-4 tells the server to start listening for requests.

Now we have an Express server listening for requests, but we haven't yet built the form that it needs to send back if it receives a request.

Make a new file called index.html and paste the following code into it:

<!DOCTYPE html>
<html lang="en">
<body>
<form action="/create" method="GET">
  <input type="submit" value="Create">
</form>

</body>
</html>

This is a straightforward bit of HTML that puts a single button on the page. When this button is clicked, it sends a GET request to /create, which the server will then respond to according to the code that we wrote above - in our case, it will send back the create.html file which we will define now.

Make a new file called create.html and paste the following into it:

<!DOCTYPE html>
<html lang="en">
<body>

<h2>Customer details</h2>

<form action="/create" method="POST">
  <label for="name" >Customer name *</label><br>
  <input type="text" id="name" name="name" class="textInput" placeholder="John Smith" required>
  <br>
  <label for="address" >Customer address *</label><br>
  <input type="text" name="address" class="textInput" placeholder="42 Wallaby Way, Sydney" required>
  <br>
  <label for="telephone" >Customer telephone *</label><br>
  <input type="text" name="telephone" class="textInput" placeholder="+275554202" required>
  <br>
  <label for="note" >Customer note</label><br>
  <input type="text" name="note" class="textInput" placeholder="Needs a new pair of shoes">
  <br><br>
  <input type="submit" value="Submit">
</form>

</body>
</html>

We won't go in-depth into the above HTML. It is a very basic form with four fields (name, address, telephone, note) and a submit button, which creates an interface that will look like the one below.

When the user presses the submit button, a POST request is made to /create with the data in the form - we still have to handle this request in our code as we're currently only handling a GET request to /.

If you click the "Run" button now, a new window should appear on the right that displays the "Create" button we defined just now in index.html. To see the form, you can also navigate to https://<repl_name>.<your_username>.repl.co, replacing with whatever you named your repl (but with no underscores or spaces) and with your repl username. You will be able to see this URL in the repl itself.

If you select "Create" and then fill in the form and hit submit, you'll get a response that says

Cannot POST /create

. This is because we haven't added the code that handles the form POST request, so let's do that.

Add the following code into your index.js file, below the app.get entry that we made above:

app.post('/create', function (req, res, next) {
  client.connect(err => {
    const customers = client.db("crmdb").collection("customers");

    let customer = {name: req.body.name, address: req.body.address, telephone: req.body.telephone, note: req.body.note};
    customers.insertOne(customer, function (err, res) {
      if (err) throw err;
      console.log("1 customer inserted");
    });
  })
  res.send('Customer created');
})

Line 1 defines a new route that listens for an HTTP POST request at /create.
Line 2 connects to the database. This happens asynchronously, so we define a callback function that will be called once the connection is made.
Line 3 creates a new collection of customers. Collections in MongoDB are similar to tables in SQL.
Line 5 defines customer data that will be inserted into the collection. This is taken from the incoming request. The form data is parsed using the parsers that we defined earlier and is then placed in the req.body variable for us to use in the code.
Line 6 inserts the customer data into the collection. This also happens asynchronously, and so we define another callback function that will get an error if an error occurred, or the response if everything happened successfully.
Line 7 throws an error if the above insert had a problem.
Line 8 gives us some feedback that the insert happened successfully.

If you run the repl now (you may need to refresh it) and submit the filled-in form, you'll get a message back that says "Customer created". If you look in your cluster in MongoDB and select the "Collections" button, you'll see a document has been created with the details that we submitted in the form.

Updating and deleting database entries

As a final step in this tutorial, we want to be able to update and delete database documents in our collection. To make things simpler, we're going to make a new HTML page where we can request a document and then update or delete it.

First, let's make the routes to our new page. In your index.js, add the following code below the rest of your routing code (i.e. before the MongoDB code):

app.get('/get', function (req, res) {
  res.sendFile('/get.html', {root: '.'});
});

app.get('/get-client', function (req, res) {
    client.connect(err => {
        client.db("crmdb").collection("customers").findOne({name: req.query.name}, function(err, result) {
          if (err) throw err;
          res.render('update', {oldname: result.name, oldaddress: result.address, oldtelephone: result.telephone, oldnote: result.note, name: result.name, address: result.address, telephone: result.telephone, note: result.note});
        });
      });
});

Line 1-3 tells Express to respond to incoming GET requests on /get by sending the get.html file which we will define below.
Line 5-12 tells Express to respond to incoming GET requests on /get-client.
- Line 7 makes a call to the database to fetch a customer by name. If there is more than one customer with the same name, then the first one found will be returned.
- Line 9 tells Express to render the update template, replacing variables with the given values as it goes. Important to note here is that we are also replacing values in the hidden form fields we created earlier with the current values of the customer details. This is to ensure that we update or delete the correct customer.

In your index.html file, add the following code after the </form> tag:

<br>
<form action="/get" method="GET">
  <input type="submit" value="Update/Delete">
</form>

This adds a new button that will make a GET request to /get, which will then return get.html.

Make a new file called get.html with the following contents:

<!DOCTYPE html>
<html  lang="en">
<body>
<form action="/get-client" method="GET">
  <label for="name">Customer name *</label><br>
  <input type="text" id="name" name="name" class="textInput" placeholder="John Smith" required>
  <input type="submit" value="Get customer">
</form>
</body>
</html>

This makes a simple form with an input for the customer's name and a button.

Clicking this button will make a GET request to /get-client, which will respond with the client details, and we will be able to update or delete them.

To see the customer details on a form after requesting them, we need a templating engine to render them onto the HTML page and send the rendered page back to us. With a templating engine, you define a template - a page with variables in it - and then give it the values you want to fill into the variables. In our case, we're going to request the customer details from the database and tell the templating engine to render them onto the page.

We're going to use a templating engine called Pug. Pug is a simple templating engine that integrates fully with Express. The syntax that Pug uses is very similar to HTML. One important difference in the syntax is that spacing is very important as it determines your parent/child hierarchy.

First, we need to tell Express which templating engine to use and where to find our templates. Put the following line above your route definitions (i.e. after the other app.use lines in index.js):

app.engine('pug', require('pug').__express)
app.set('views', '.')
app.set('view engine', 'pug')

Now create a new file called update.pug with the following content:

html
  body
    p #{message}
    h2= 'Customer details'
    form(method='POST' action='/update')
      input(type='hidden' id='oldname' name='oldname' value=oldname)
      input(type='hidden' id='oldaddress' name='oldaddress' value=oldaddress)
      input(type='hidden' id='oldtelephone' name='oldtelephone' value=oldtelephone)
      input(type='hidden' id='oldnote' name='oldnote' value=oldnote)
      label(for='name') Customer name:
      br
      input(type='text', placeholder='John Smith' name='name' value=name)
      br
      label(for='address') Customer address:
      br
      input(type='text', placeholder='42 Wallaby Way, Sydney' name='address' value=address)
      br
      label(for='telephone') Customer telephone:
      br
      input(type='text', placeholder='+275554202' name='telephone' value=telephone)
      br
      label(for='note') Customer note:
      br
      input(type='text', placeholder='Likes unicorns' name='note' value=note)
      br
      button(type='submit' formaction="/update") Update
      button(type='submit' formaction="/delete") Delete

This is very similar to the HTML form we created previously for create.html, however this is written in the Pug templating language. We're creating a hidden element to store the "old" name, telephone, address, and note of the customer - this is for when we want to do an update.

Using the old details to update the customer is an easy solution, but not the best solution as it makes the query cumbersome and slow. If you add extra fields into your database, you would have to remember to update your query as well, otherwise it could lead to updating or deleting the wrong customer if they have the same information. A better but more complicated way is to use the unique ID of the database document, as that will only ever refer to one customer.

We have also put in placeholder variables for name, address, telephone, and note, and we have given the form two buttons with different actions.

If you now run the code, you will have an index page with two buttons. Pressing the "Update/Delete" button will take you to a new page that asks for a customer name. If you fill in the customer name and press "Get customer", a page will load with the customer's details and two buttons below, "Update" and "Delete". Make sure you enter a customer name you have entered before.

Our next step is to add the "Update" and "Delete" functionality. Add the following code below your routes in index.js:

app.post('/update', function(req, res) {
  client.connect(err => {
    if (err) throw err;
    let query = { name: req.body.oldname, address: req.body.oldaddress, telephone: req.body.oldtelephone, note: req.body.oldnote };
    let newvalues = { $set: {name: req.body.name, address: req.body.address, telephone: req.body.telephone, note: req.body.note } };
    client.db("crmdb").collection("customers").updateOne(query, newvalues, function(err, result) {
        if (err) throw err;
        console.log("1 document updated");
        res.render('update', {message: 'Customer updated!', oldname: req.body.name, oldaddress: req.body.address, oldtelephone: req.body.telephone, oldnote: req.body.note, name: req.body.name, address: req.body.address, telephone: req.body.telephone, note: req.body.note});
      });
  });
})

app.post('/delete', function(req, res) {
  client.connect(err => {
    if (err) throw err;
    let query = { name: req.body.name, address: req.body.address ? req.body.address : null, telephone: req.body.telephone ? req.body.telephone : null, note: req.body.note ? req.body.note : null };
    client.db("crmdb").collection("customers").deleteOne(query, function(err, obj) {
      if (err) throw err;
      console.log("1 document deleted");
      res.send(`Customer ${req.body.name} deleted`);
    });
  });
})

This introduces two new POST handlers - one for /update, and one for /delete.

Line 2 connects to our MongoDB database.
Line 3 throws an error if there was a problem connecting to the database.
Line 4 defines a query that we will use to find the document to update. In this case, we'll use the details of the customer before it was updated. We saved this name earlier in a hidden field in the HTML. Trying to find the customer by its updated name obviously won't work, because it hasn't been updated yet. Also, note that we are setting some of the fields to null if they are empty. This is so that the database returns the correct document when we update or delete - if we search for a document that has no address with an address of '' (empty string), then our query won't return anything.
Line 5 defines the new values that we want to update our customer with.
Line 6 updates the customer with the new values using the query.
Line 7 throws an error if there was a problem with the update.
Line 8 logs that a document was updated.
Line 9 re-renders the update page with a message saying that the customer was updated, and displays the new values.
Line 15 connects to our MongoDB database.
Line 16 throws an error if there was a problem connecting to the database.
Line 17 defines a query that we will use to find the document to delete. In this case, we use all the details of the customer before any changes were made on the form to make sure we delete the correct customer.
In Line 18, we connect to the database and delete the customer.
Line 19 throws an error if there was a problem with the delete.
Line 20 logs that a document was deleted.
Line 21 sends a response to say that the customer was deleted.

Putting it all together

If you run your application now, you'll be able to create, update, and delete documents in a MongoDB database. This is a very basic CRUD application, with a very basic and unstyled UI, but it should give you the foundation to build much more sophisticated applications.

Some ideas for this are:

You could add fields to the database to classify customers according to which stage they are in your sales pipeline so that you can track if a customer is potentially stuck somewhere and contact them to re-engage.
You could integrate some basic marketing automation with a page allowing you to send an email or SMS to customers (though don't spam clients!).
You could also add fields to keep track of customer purchasing information so that you can see which products do well with which customers.

If you want to start from where this tutorial leaves off, fork the repl at https://replit.com/@ritza/replcrm.
To get additional guidance from the Replit community, you can join Replit's Discord server by using this invite link https://replit.com/discord.

https://replit.com/@ritza/replcrm

Building a Discord bot with Node.js and Replit

RitzaCo — Mon, 12 Sep 2022 08:31:21 +0000

In this tutorial, we'll use Replit and Node.js to build a Discord chatbot. The bot will be able to join a Discord server and respond to messages.

If you prefer Python, here's a Python Discord bot tutorial.

You'll find it easier to follow along if you have some JavaScript knowledge and you should have used Discord or a similar app such as Skype or Telegram before. We won't be covering the very basics of Node.js, but we will explain each line of code in detail, so if you have any experience with programming, you should be able to follow along.

Overview and requirements

We'll be doing all of our coding through the Replit web IDE, and we'll host our bot with Replit too, so you won't need to install any additional software on your machine. For this tutorial you will need to create a Discord account (if you already have one, you can skip this).

We will cover:

Creating an application and a bot user in your Discord account.
Creating a server on Discord.
Adding our bot to our Discord server.

Let's get through these admin steps first and then we can get to the fun part of coding our bot.

Creating a bot in Discord and getting a token

You can sign up for a free account over at Discord, and you can download one of their desktop or mobile applications from the Discord homepage. You can also use Discord in the browser.

Once you have an account, you'll want to create a Discord application. Visit the Discord developer's page and press the "New application" button, as in the image below.

Fill out a name for your bot and select "Create".

The first thing to do on the next page is to note your Application ID, which you'll need to add the bot to the server. You can come back later and get it from this page, or copy it somewhere so you can find it when you need it.

You can also rename the application and provide a description for your bot, then press "Save Changes".

You have now created a Discord application. The next step is to add a bot to this application, so head over to the "Bot" tab using the menu on the left and press the "Add Bot" button, as shown below. Click "Yes, do it" when Discord asks if you're sure about bringing a new bot to life.

The last thing we'll need from our bot is a token. Anyone who has the bot's token can prove that they own the bot, so you'll need to be careful not to share this with anyone. You can get the token by pressing "Reset Token", and then copy it to your clipboard by pressing "Copy".

Take note of your token or copy it to your clipboard, as we'll need to add it to our code soon.

Creating a Discord server

If you don't have a Discord server to add your bot to, you can create one by either opening the desktop Discord application that you downloaded earlier or returning to the Discord home page in your browser. Press the "+" icon, as shown below, to create a server.

Press "Create a server" in the screen that follows, and then give your server a name. Once the server is up and running, you can chat with yourself, or invite some friends to chat with you. Soon we'll invite our bot to chat with us as well.

Adding your Discord bot to your Discord server

Our Discord bot is still just a shell at this stage as we haven't written any code to allow it to do anything, but let's go ahead and add the bot to our Discord server anyway. To add a bot to your server, you'll need the Application ID from the "General Information" page that we looked at before when we created our ReplBotApplication (ie. the application ID, not the secret bot token).

Create a URL that looks as follows, but using your application ID instead of mine at the end (the link calls the application ID "client_id"):

https://discordapp.com/api/oauth2/authorize?scope=bot&client_id=746269162917331028

Visit the URL that you created in your web browser and you'll see a page similar to the following where you can choose which server to add your bot to.

Select the server we created in the step before this and hit the "Authorize" button. After completing the captcha, you should get an in-app Discord notification telling you that your bot has joined your server.

Now we can get to the fun part of building a brain for our bot!

Creating a repl and installing our Discord dependencies

The first thing we need to do is create a Node.js repl to write the code for our Discord bot. Over at Replit, create a new repl, choosing "Node.js" as your language.

We don't need to reinvent the wheel as there is already a great Node wrapper for the Discord bot API called discord.js. Normally we would install this third-party library through npm, but because we're using Replit, we can skip the installation. Our repl will automatically pull in all dependencies.

In the default index.js file that is included with your new repl, add the following line of code:

const Discord = require('discord.js');

Press the "Run" button and you should see Replit installing the Discord library in the output pane on the right, as in the image below.

Our bot is nearly ready to go - but we still need to plug in our secret token. This will authorize our code to control our bot.

Setting up authorization for our bot

By default, Replit code is public. This is great as it encourages collaboration and learning, but we need to be careful not to share our secret bot token (which gives anyone who has access to it full control of our bot).

To get around the problem of needing to give our code access to the token while allowing others to access our code but not our token, we'll be using environment variables. Replit allows us to set secret environment variables through the "Secrets (Environment variables)" menu option.

Open the "Secrets" menu option. There you will be able to set environment variables for your repl. Set the key as the name of your environment variable to DISCORD_BOT_SECRET. Set the value as your bot's secret token (note that this is the second token that we got while setting up the bot -- different from the Application ID that we used to add our bot to our server). It should look something like:

Let's make a Discord bot that repeats everything we say but in reverse. We can do this in just a few lines of code. In your index.js file, add the following:

const Discord = require("discord.js");
const client = new Discord.Client({
  intents: [
    "GUILDS",
    "GUILD_MESSAGES",
  ],
});

const token = process.env['DISCORD_BOT_SECRET']

client.on('ready', () => {
  console.log("I'm in");
  console.log(client.user.username);
});

client.on('messageCreate', msg => {
    if (msg.author.id != client.user.id) {
        msg.channel.send(msg.content.split('').reverse().join(''));
    }
});

client.login(token)

Let's tear this apart line by line to see what it does.

Line 1 is the line we added earlier. This line tells Replit to install the third party library and brings it into this file so that we can use it.
In line 2, we create a Discord Client. We'll use this client to send commands to the Discord server to control our bot and send it commands.
In line 3-8, we provide the intents of our Client, these are provided to designate which events our bot will be able to receive.
In line 9, we retrieve our secret token from the environment variables (which Replit sets from the "Secrets" menu).
In line 11, we define an event for our client, which defines how our bot should react to the ready event. The Discord bot is going to run asynchronously, which might be a bit confusing if you're used to running standard synchronous code. We won't go into asynchronous coding in-depth here, but if you're interested in what this is and why it's used, there's a good guide over at RisingStack. In short, instead of running the code in our file from top to bottom, we'll be running pieces of code in response to specific events.
In lines 12-14, we define how our bot should respond to the ready event, which is fired when our bot successfully joins a server. We instruct our bot to output some information server-side (i.e. it will be displayed in our repl's output, but not sent as a message through to Discord). We'll print a simple "I'm in" message to see that the bot is there and print our bot's username (if you're running multiple bots, this will make it easier to work out who's doing what).
Lines 16-20 are similar, but instead of responding to a ready event, we tell our bot how to handle new messages. Line 17 says we only want to respond to messages that aren't from us (otherwise our bot will keep responding to himself -- you can remove this line to see why that's a problem), and line 18 says we'll send a new message to the same channel we received a message in (msg.channel) and the content we'll send will be the same message that we received, but backwards. To reverse a string, we split it into its individual characters, reverse the resulting array, and then join it all back into a string again.

The last line fires up our bot and uses the token we loaded earlier to log into Discord.

Press the "Run" button again and you should see your bot reporting a successful channel join in the repl output.

Open Discord, and from within the server we created earlier, you will be able to send a message (by typing into the box highlighted below) and see your bot respond!

The bot responds each time, reversing the text we enter.

Keeping our bot alive

Your bot can now respond to messages, but only for as long as your repl is running. If you close your browser tab or shut down your computer, your bot will stop and no longer respond to messages on Discord.

Replit will keep your code running after you close the browser tab only if you are running a web server. Our bot doesn't require an explicit web server to run, but we can create a server and run it in the background just to keep our repl alive.

Create a new file in your project called keep_alive.js and add the following code:

var http = require('http');

http.createServer(function (req, res) {
  res.write("I'm alive");
  res.end();
}).listen(8080);

We won't go over this in detail as it's not central to our bot, but here we start a web server that will return "I'm alive" if anyone visits it.

In our index.js file, we need to add a require statement for this server at the top. Add the following line near the top of index.js:

const keep_alive = require('./keep_alive.js')

After doing this and hitting the green "Run" button again, you should see some changes to your repl. For one, you'll see a new pane in the top right that shows the web output from your server. We can see that visiting our repl now returns a basic web page showing the "I'm alive" string that we told our web server to return by default.

Now your bot will stay alive even after closing your browser or shutting down your development machine. Replit will still clean up your server and kill your bot after about one hour of inactivity, so if you don't use your bot for a while, you'll have to log into your repl and start the bot up again. Alternatively, you can set up a third-party (free!) service like Uptime Robot. Uptime Robot pings your site every five minutes to make sure it's still working -- usually to notify you of unexpected downtime, but in this case the constant pings have the side effect of keeping our repl alive as it will never go more than an hour without receiving any activity. Note that you need to select the "HTTP" option instead of the "Ping" option when setting up Uptime Robot, as Replit requires regular HTTP requests to keep your chatbot alive, or you can use an Always-on repl to keep it running 24/7.

Forking and extending our basic bot

This is not a very useful bot as-is, but the possibilities are only limited by your creativity now! You can have your bot receive input from a user, process the input, and respond in any way you choose. In fact, with the basic input and output that we've demonstrated, we have most of the components of any modern computer, all of which are based on the Von Neumann architecture (we could easily add the missing memory by having our bot write to a file, or with a bit more effort link in a SQLite database for persistent storage).

If you followed along with this tutorial, you'll have your own basic repl bot to play around with and extend. If you were only reading, you can easily fork my bot at https://replit.com/@ritza/discord-bot-node-1 and extend it however you like (you'll need to add your own token and reset the secrets still). Happy hacking!

If you're stuck for ideas, you could try link up your Discord bot to the Twitch API to get notified when your favorite streamers are online, or build a text adventure.

Card game with pygame

RitzaCo — Wed, 07 Sep 2022 07:59:11 +0000

Card games are a great way to learn how to program. We get to build a model of the game, game logic, and a visual interface.

A classic card game is Snap. The rules are pretty simple, which makes it great for building a first card game. We can spend more time on the modelling and visualization, which can be used on other card games too.

The game rules

To simplify this tutorial, we'll limit our game to 2 players. Here's the rules for our 2 player game:

The deck is shuffled, and dealt evenly between the two players.
Each player takes turns drawing a card and places it face up on top of the last card drawn.
If the card placed is a match (by value) of the previous card, the first player to call "Snap!" wins the entire pile of cards. These cards are added to their hand.
If a player calls "Snap!" and the card placed is not a match (i.e. falsely calls "Snap!"), then the other player takes the pile of cards.
The first player to run out of cards loses, and the other player wins.

Creating a new project

Let's head over to Replit and create a new repl. Choose Pygame as the template to create a repl from. Now, give this repl a name, like "SnaPy".

After the repl has booted up, you should see a main.py file. We'll use this file for the main game loop, but we'll create other files for the game models and logic.

For our Snap game, we'll need some images of cards to display. Create a folder called images in the file explorer of your repl.

Now download these card images to your computer. Unzip the file, and drag and drop the images it contains to the images folder in your repl.

Getting started with pygame

A popular game framework in Python is pygame. It has functionality to draw shapes and images to the screen, get user input, play sounds and more. We'll use some of the basic functionality in this game to see how it works.

We can import it into our project by adding the following line to our main.py file:

import pygame

To get the pygame framework started, we need to add some initialization code:

pygame.init()
bounds = (1024, 768)
window = pygame.display.set_mode(bounds)
pygame.display.set_caption("SnaPy")

Line 1 starts up the pygame system, by initializing its modules (for example, the font, sound and graphics code).
Line 2 creates a new tuple called bounds. This tuple contains the dimensions of the window that we'll run our Snap game in.
Line 3 creates a new window for us to display our game in.
Line 4 gives the window a caption, or title. This can be whatever you'd like to call the game.

If you run the project, using the "Run" button at the top center of the Repl, you should see a small blank window come up. That means everything is initialized and working so far. Not much, but it's our blank canvas to get started with!

Designing the game model

Python is an object-oriented language. With object-oriented programming, we identify different parts and entities of the game and model them as classes and objects. Let's draw the game, and see what parts we need to model.

From the above image, we can see that we can model the following:

Individual cards
A deck of cards, which is a collection of all the cards
Players, with their hand of cards and name
A pile of cards, which is a collection of cards that are face up on the table

Note that this is one way to group the game parts, but it is not the only way. There are many ways to identify individual objects, and a big factor is how granular you need to be, and how responsibilities are assigned. This is part art, part experience and part computer science. Often we start with a model design, and then refine it over time as we learn more about the game and the dynamics of the model.

We'll also need logic to control the rules and the state of the game. Often this part of the program is known as the "game engine". We'll model this as a class as well.

Here is a diagram of all the classes we'll build.

The classes have some of the key properties and methods that they will need.

Building the game model

Let's start by building the Card class. This class will represent a single card.

Create a new file called models.py in Replit. Inside this file we can define the Card class.

At the top of the file, add in some package imports:

Enum for enumerations (which we'll use for defining the card suits).
pygame, to load up the card images.
random, to use when we shuffle the deck.

from enum import Enum
import pygame
import random

Now let's add in the suits we'll need for the cards. We'll use the Enum class to define the different suits.

class Suits(Enum):
  CLUB = 0
  SPADE = 1
  HEART = 2
  DIAMOND = 3

Alright, the boilerplate is out of the way. Now, lets define the Card class.

class Card:
  suit = None
  value = None
  image = None

  def __init__(self, suit, value):
    self.suit = suit
    self.value = value
    self.image = pygame.image.load('images/' + self.suit.name + '-' + str(self.value) + '.svg')

From this small class, we can see the various parts of a Python class. The first line is the class definition. The next 3 lines are the class properties (variables that are controlled by objects made from the class). Then we have the __init__ method, which is called the constructor method. This is where we initialize the class. In this case, we'll initialize the suit and value properties for the card. We'll also load the image for the card using Pygame's image.load function, with the filepath constructed from the suit and value. This implies that all the card images are all actually named according to the suit and value.

Now that we have suits and cards, let's create a Deck of cards.

class Deck:
  cards = None

  def __init__(self):
    self.cards = []
    for suit in Suits:
      for value in range(1,14):
        self.cards.append(Card(suit, value))

  def shuffle(self):
    random.shuffle(self.cards)

  def deal(self):
    return self.cards.pop()

  def length(self):
    return len(self.cards)

The Deck class is a collection of cards. It has a list of cards, and a few methods to manipulate the list.

The constructor, __init__ initializes the cards list, and populates it with all the cards in a deck, using 2 for loops. The first loop iterates over the Suits enum, and the second loop iterates over the values 1 through 13, which is all the cards in a deck.

Every deck of cards needs to be shuffled before it is used, so we've defined a shuffle method. Python's random module has a very handy shuffle function built in that we can use. shuffle takes a list and rearranges the contents of that list in place (i.e. it doesn't return a new list).

Then we have the deal method, which removes the last card from the list and returns it. We'll use this to deal the cards to the players.

We have a length method that we'll use to determine if there are any cards left in the deck. This will be useful when dealing out cards to know when to stop.

The Deck class is now complete.

Let's move to the Pile class. This class models the pile of cards face up on the table, that each player adds to when playing.

class Pile:
  cards = None

  def __init__(self):
    self.cards = []

  def add(self, card):
    self.cards.append(card)

  def peek(self):
    if (len(self.cards) > 0):
      return self.cards[-1]
    else:
      return None

  def popAll(self):
    return self.cards

  def clear(self):
    self.cards = []

  def isSnap(self):
    if (len(self.cards) > 1):
      return (self.cards[-1].value == self.cards[-2].value)
    return False

The Pile class has one main property: a list of cards, which is initialized in the constructor.

The add method is used when a player plays a card, i.e. adds it to the pile.

The peek method returns the top card of the pile, while still keeping it on the pile. We'll use this to draw the top card, as it is face up. If there are no cards on the pile, indicated by the length of the card array being 0, we'll return None.

When a player wins, they get all the cards on the pile. The popAll method handles this by returning the list of cards. Then we can call the clear method to remove all the cards from the pile.

If a player calls "Snap!", we need to check if the top two cards are the same value. We'll use the isSnap method to check this. Python has a handy feature of negative indices. This means an index of -1 returns the last element in the list, -2 returns the second last, and so on. This allows us to easily get the last 2 cards added to the pile, and check if they are the same value. Note that in the rules of Snap, only the value is important - the suit is not used.

The last of the models is the Player class.

class Player:
  hand = None
  flipKey = None
  snapKey = None
  name = None

  def __init__(self, name, flipKey, snapKey):
    self.hand = []
    self.flipKey = flipKey
    self.snapKey = snapKey
    self.name = name

  def draw(self, deck):
    self.hand.append(deck.deal())

  def play(self):
    return self.hand.pop(0)

The Player class has a few properties. The hand property is a list of cards that the player has.

The flipKey and snapKey properties are the keys assigned to player that they use to flip and snap cards.

The name property is the name of the player.

The draw method is used to draw a card from the deck passed in the arguments. The draw method calls the deal method on the deck, and adds the card to the hand list.

The play method pops a card off the hand list, used when the player plays a card.

Building the game engine

Ok, time to build the game engine that will coordinate the interactions between the models we created.

Make a new file called engine.py. Let's start by adding the libraries we'll need.

from enum import Enum
import pygame
from models import *

Besides the Enum and pygame libraries, we import everything, *, from our models.py file. This way we can use all the classes that we defined in models.

A common element in game engines is keeping track of the state of the game. We'll define a GameState enumeration to keep track of the state of the game.

class GameState(Enum):
  PLAYING = 0
  SNAPPING = 1
  ENDED = 2

We only have 3 states, or phases, of the game that we will track. The first is PLAYING, which is the main phase of the game, where the players take turns putting down cards. The second is SNAPPING. This is the state the game is in when a player calls "Snap!". In this state, we check if the snap is valid, and also wait until the players are ready to resume playing. The third is ENDED, which is the phase where the game is over, i.e. one player has no more cards to play.

Now, let's start with the engine itself. First, let's add the definition, properties and constructor:

class SnapEngine:
  deck = None
  player1 = None
  player2 = None
  pile = None
  state = None
  currentPlayer = None
  result = None

  def __init__(self):
    self.deck = Deck()
    self.deck.shuffle()
    self.player1 = Player("Player 1", pygame.K_q, pygame.K_w)
    self.player2 = Player("Player 2", pygame.K_o,pygame.K_p)
    self.pile = Pile()
    self.deal()
    self.currentPlayer = self.player1
    self.state = GameState.PLAYING

In the properties, we define the deck of cards, players, pile of cards, and the state of the game. We also have a currentPlayer property, which keeps track of the player whose turn it is. The result property is used to communicate the outcome of a round, or the entire game.

The constructor initializes objects and stores them in the properties. Note that we assign default names and keys to the players.

We also call a method we have yet to define, deal, to deal the cards to the players.

We start off the game by setting the state to PLAYING, and the currentPlayer to player1.

Let's add some more methods and logic to the engine. To start, the deal method:

  def deal(self):
    half = self.deck.length() // 2
    for i in range(0, half):
      self.player1.draw(self.deck)
      self.player2.draw(self.deck)

The deal method is in charge of making sure each player gets half the deck of cards. There are a few ways to do this - this code takes a bit of a literal translation of dealing, by dealing one card to each player alternately. In practice, we'll use a for loop to do this, and in the loop we'll call the draw method on each of the players to draw a card.

Since each round of the for loop takes a card for each player, 2 cards per loop, we only need to loop for half the number of cards in the deck.

To find the middle of the deck, we get the length of the deck, and divide it by 2. Note that we use the // integer division operator to get back an integer after division, as the meaning of the middle is the index of the middle card. A number with decimals wouldn't make any sense here.

Next, we can add a helper method to switch the current player. We'll use this after each player plays a card to indicate that it's the next player's turn.

  def switchPlayer(self):
    if self.currentPlayer == self.player1:
      self.currentPlayer = self.player2
    else:
      self.currentPlayer = self.player1

Here we check which player is the current player and switch currentPlayer to the other player.

The last helper method we need on the engine is one that handles a player winning a round (by calling "Snap!" correctly, or the other player falsely calling "Snap!"). This method will change the state of the game. It will also add all the cards on the pile to the winner's hand. Then it will clear out the pile so the next round can start:

  def winRound(self, player):
    self.state = GameState.SNAPPING
    player.hand.extend(self.pile.popAll())
    self.pile.clear()

Now we get to the main logic of the engine. This method will be called from our main game loop, which we will define later. Let's start with the method definition and some basic checks. Then we'll add the logic in sections. Start by adding this method to the engine:

  def play(self, key):
    if key == None: 
      return

    if self.state == GameState.ENDED:
      return

We'll call this main logic method play. It takes whatever key is currently pressed, and processes the logic for that. The first thing we check is if a key has actually been pressed. If it hasn't, we return, as there is nothing to update with the game state.

The next check to make is if the game is over. If it is, we return, as again, there is nothing to do. If you want to improve the game, you could listen for a key press to restart the game.

Now let's add some of the logic. The first thing is to check if the current player has pressed the key to play, or flip a card onto the pile. If they have pressed their flipKey, we call their play method and add the returned card to the pile. Then we switch turn to the next player, by calling our switchPlayer method.

    if key == self.currentPlayer.flipKey:
      self.pile.add(self.currentPlayer.play())
      self.switchPlayer()

Next, let's check if any of the players have called "Snap!". We'll need to keep track of a few things: who called "Snap!", who didn't call "Snap!", and if there is a valid snap condition on the pile. Add this logic to the play method:

    snapCaller = None
    nonSnapCaller = None
    isSnap = self.pile.isSnap()

    if (key == self.player1.snapKey):
      snapCaller = self.player1
      nonSnapCaller = self.player2
    elif (key == self.player2.snapKey):
      snapCaller = self.player2
      nonSnapCaller = self.player1

Here we create two variables, snapCaller and nonSnapCaller, which keep track of the player who called "Snap!" and the player who didn't call "Snap!". We also create a variable isSnap to keep track of whether there is a valid snap condition on the pile. Then we check if either of the players has called "Snap!". If they have, then we set the snapCaller and nonSnapCaller variables as applicable.

We now know if "Snap!" has been called and which player called it. Let's add the logic to see if the player that called "Snap!" wins or loses. Add this logic to the play method:

    if isSnap and snapCaller:
      self.winRound(snapCaller)
      self.result = {
        "winner": snapCaller,
        "isSnap": True,
        "snapCaller": snapCaller 
      }
      self.winRound(snapCaller)
    elif not isSnap and snapCaller:
      self.result = {
        "winner": nonSnapCaller,
        "isSnap": False,
        "snapCaller": snapCaller 
      }
      self.winRound(nonSnapCaller)

We have two cases: one for a valid snap, and one for an invalid snap.

If the pile is a valid snap, we call the winRound method on the player who called "Snap!". Then we set the result property to a dictionary with the winner, whether it was a valid snap, and the player who called "Snap!". This will be used for information when we make the game user interface (UI).

Likewise, for an invalid snap, we call the winRound method on the player who didn't call "Snap!". Then we set the result property to a dictionary with the winner as the nonSnapCaller.

In both cases, we call the winRound method with whichever player won the cards. Recall in the winRound method we assign the pile to the player's hand. Then we clear the pile, and set the gameState to SNAPPING.

We've got just one last thing to check: if any player has run out of cards. If they have, then it means the other player wins. Add this logic to the play method:

    if len(self.player1.hand) == 0:
      self.result = {
        "winner": self.player2,
      }
      self.state = GameState.ENDED
    elif len(self.player2.hand) == 0:
      self.result = {
        "winner": self.player1,
      }
      self.state = GameState.ENDED

If one of the players has run out of cards, then we set the result property to a dictionary with the winner as the other player. Then we set the state property to GameState.ENDED.

Setting up the game loop

We've built the model and the logic in the engine to play a game of Snap. Now we need to define the game loop to run the game.

Open up the main.py file again. We'll start by adding references to the models and engine, so that we can access them when building the UI. Add the following imports right under the import pygame line:

from models import *
from engine import *

We'll start by creating a new game engine object. Add this to the main.py file, underneath the Pygame initialization code:

gameEngine = SnapEngine()

Now the game loop. The game loop's job is to listen for user input, call the engine's play method to process that input, and update the UI with the result. Add this to the main.py file:

run = True
while run:
  key = None; 
  for event in pygame.event.get():
    if event.type == pygame.QUIT:
      run = False
    if event.type == pygame.KEYDOWN:
      key = event.key

  gameEngine.play(key)
  renderGame(window)
  pygame.display.update()

  if gameEngine.state == GameState.SNAPPING:
    pygame.time.delay(3000)
    gameEngine.state = GameState.PLAYING

We start off by defining a variable run. Then we use this as a condition for a while loop. As long as run is true, the loop will continuously run the code inside.

In Pygame, we listen for events on the event queue. We use the pygame.event.get() method to get all the events that have happened since the last time we checked. We then iterate through the events, checking if any of them is a QUIT event. If they are, we set run to false, and break out of the loop to end the program. A QUIT event is sent if the user clicks the close button on the window.

If any of the events is a KEYDOWN event, we set the key variable to the key that was pressed.

Then we call out to the game engine to process the key that was pressed.

Once that is done, we can update the UI. We call the renderGame method, which we'll get to next.

After the UI has been updated, we call the pygame.display.update() method to draw it to the screen.

The final check is to see if the game is in the SNAPPING state. If it is, we wait 3 seconds before switching back to the PLAYING state. This is so that there is enough time for the players to pause and see what happened. Remember the game loop will go around very quickly, so the delay will help them to see any messages we display in the renderGame method.

Rendering the game

The last main task is to render the game through a UI. This is where we'll use Pygame to draw the game to the screen.

In the game loop, we call the renderGame method. This method takes a window parameter, which is the Pygame window we created in the main.py file. The window is the graphics surface that we will draw to. The renderGame method will look at the state and result of the gameEngine, as well as the players, and draw the appropriate UI to the window.

Let's implement that method now. We'll start by clearing the window, and drawing some fixed UI elements. Add the following code to the main.py file, above the game loop.

cardBack = pygame.image.load('images/BACK.png')
cardBack = pygame.transform.scale(cardBack, (int(238*0.8), int(332*0.8)))

def renderGame(window):
  window.fill((15,0,169))
  font = pygame.font.SysFont('comicsans',60, True)

  window.blit(cardBack, (100, 200))
  window.blit(cardBack, (700, 200))

  text = font.render(str(len(gameEngine.player1.hand)) + " cards", True, (255,255,255))
  window.blit(text, (100, 500))

  text = font.render(str(len(gameEngine.player2.hand)) + " cards", True, (255,255,255))
  window.blit(text, (700, 500))

  topCard = gameEngine.pile.peek()
  if (topCard != None):
    window.blit(topCard.image, (400, 200))

Firstly we load an image of the back of a card outside the function. We do this to avoid loading it each time the screen is rendered - this way it is only loaded once. We will use this image to represent the cards in the players' hands, which are face down. pygame's transform.scale function is used to scale the image to 0.8 the size of the regular card size. This is just to indicate visually that they are in the background to the main part of the UI, which will be the card at top of the pile.

Inside the renderGame function, we first clear the window. We use the fill method to fill the window with a color, (15,0,169) in RGB (Red Green Blue) color notation, which is a dark blue color.

Then we choose a font to use. We use the SysFont method to load a font from the system. We pass in the font name, the font size, and a boolean value indicating whether the font should be bold.

Next is to draw the card backs representing the players' hands. We use the blit method to draw the card back to the window. We pass in the card back image we loaded outside the function, and the screen coordinates we want to draw it at. We draw two card backs, one for each player, one on the far left of the screen, and the other on the far right. We'll draw the pile between these two hands.

To indicate the current score of the game, we render text showing the number of cards each player currently holds. First, we construct a text object using the font's render method. We pass in the text we want to render (which is the player's card count and the word 'cards'), and the color we want to use. We then draw the text to the screen by blitting it to the window.

The last part of the code draws the card at the top of the pile. We use the peek method we implemented on the Pile class to get the top card. If there is no top card, we don't draw anything. Recall that for each card, we loaded its image in the constructor. This means we can get the image object from the image property on the card, without loading it here. Once again we blit the card image to the screen, this time passing in coordinates between the two hands.

The next part of the UI to draw is some indication of the current state of the game, and whose turn it is. We'll use the state property of the gameEngine to determine what to draw. We'll use if statements to draw the appropriate UI, based on the game state. There are three states to consider:

PLAYING The game is in progress, and we are waiting for the current player to flip a card, or either player to call "Snap!". In this case, we render the current player's name and a message to indicate that it is their turn to flip. This message is written in white (255,255,255) near the top left of the window.
SNAPPING A player has called snap. In this case, the message rendered depends on if the snap was valid or not. We can get this information from the result property of the gameEngine.
ENDING The game is over. In this case, we render the winner's name, and a message to indicate that they won.

Add this code to the renderGame function, to implement the above logic:

  if gameEngine.state == GameState.PLAYING:
    text = font.render(gameEngine.currentPlayer.name + " to flip", True, (255,255,255))
    window.blit(text, (20,50))

  if gameEngine.state == GameState.SNAPPING:
    result = gameEngine.result
    if result["isSnap"] == True:
      message = "Winning Snap! by " + result["winner"].name
    else:
      message = "False Snap! by " + result["snapCaller"].name + ". " + result["winner"].name + " wins!"
    text = font.render(message, True, (255,255,255))
    window.blit(text, (20,50))

  if gameEngine.state == GameState.ENDED:
    result = gameEngine.result
    message = "Game Over! " + result["winner"].name + " wins!"
    text = font.render(message, True, (255,255,255))
    window.blit(text, (20,50))

Running the game

Now that we have implemented the game, we can give it a test run. Click the big green "Run" button at the top of your repl. You should see the game start up, prompting "Player 1" to flip a card.

Player 1's keys are q to flip a card, and w to call snap.
Player 2's keys are o to flip a card, and p to call snap.

Call over a friend and see who's the quickest finger on calling "Snap!".

Next steps

Congratulations! You've implemented a card game. You can use the ideas and principles from this tutorial to implement a card game of your own.

Some ideas to add features to this game are:

Add a timer to the game, so that the player has a limited amount of time to flip a card.
Add some sound effects, using the Pygame mixer module.
Add a key to restart the game after it ends. Currently, at the end of the game, the players would need to close the window and start the game to play again.
Try with different cards. For example, you could use a simplified card set, perhaps themed on something you love, like Pokemons, dinosaurs, cars, celebrities, etc.

You can find our repl below:

https://replit.com/@ritza/SnaPy

Packaging software with Nix

RitzaCo — Fri, 02 Sep 2022 08:48:51 +0000

Replit's repls are powered by Nix. Nix is a tool for managing software packages and system configurations. The Nix community also maintains the Nix Packages Collection (Nixpkgs), Nix's official package repository. It contains over 50,000 projects. Chances are high that the software you need is already in there! You can search for packages on the NixOS website (DuckDuckGo users can use the !nixpkg bang command).

However, despite being the largest repository of packaged software (at the time of writing), there is software that has not been packaged in the Nix Package Set. If you need something packaged in order to use it in Nix, you can make a packaging request, but then you have to wait for a volunteer to package it for you. It's much quicker to learn how to package it yourself!

Packaging software with Nix is easier than for most other repositories. The Nix language is a DSL specifically designed for packaging software. It's partly why Nixpkgs has the most packages despite having only about a sixth of the maintainers of the repository with the most maintainers, AUR (2182 vs 12292).

An exhaustive breakdown of all the ins and outs of packaging for Nix is out of the scope of this article, but we'll take a look at the principles of packaging software and show you how to package some simple examples.

To begin with, let's talk about fetching software. Before we can package anything, we need to get a copy of it.

Fetching software

Before we can build a package, we need to fetch either the source code, or if the source code is not available, the binary file. Nix has many different fetchers we can use to fetch files.

Nix tries hard to be reproducible, that is, to ensure that whenever you build a package with the same inputs, it gives you the exact same result. When we're fetching things from the network, we need to be sure that what we've received is the thing we expected. That's why Nix fetchers all require you to supply a hash of the expected file. A hash is a short, distinctive representation of some data. It's like a digital fingerprint. If the hash of the file we downloaded matches the hash we expected, we can be sure we got the exact file we expected. Nix supports md5, sha1, sha256, and sha512 hashes, though the first two are deprecated and should no longer be used.

How do you get the hash of the file? Some projects will list hashes or checksums of their downloads on their website. If they do, use what they give you. If not, you could download it yourself, and then run a program like sha256sum to get the hash. This works well for simple files, but becomes a bit harder when you're using a fetcher like fetchFromGitHub to fetch a specific version of a Git repository. An easy workaround is to fill in a nonsensical value for the hash, and then attempt to build the package. Nix will abort the build after fetching because the hash won't match, but it will print the hash of what it fetched to the console. You can copy this value and use it as the correct hash. Re-running the build should now succeed.

Alternatively, there are also some command-line tools that can prefetch a file for you. They will fetch the file, put it in the Nix store, and print out the hash to the console. The nix-prefetch-url command comes installed in a standard Nix environment, including Replit repls. Both nix-prefetch-git and nix-prefetch-github are in Nixpkgs (so they can be installed easily using replit.nix) and work similarly. For more advanced uses, consider using nix-prefetch, also in Nixpkgs, which can prefetch using any Nix fetcher.

When updating the version of something that's fetched, be sure to change the hash, too. Internally, Nix uses the hashes to identify things, and if it hasn't changed and Nix has already got a copy downloaded from before, Nix may silently use that instead of actually attempting to fetch the file again.

Fetch files and archives with `fetchurl` and `fetchzip`

The simplest fetcher is fetchurl. It will fetch a file and put it in the Nix store. The fetchzip fetcher is very similar, but it will unpack the archive before storing it in the Nix store. This is useful if you need to refer to specific files from the archive, rather than the download as a whole. Despite its name, it can handle many different archive formats, not just zip files. In general, unless you need to refer to a specific file in an archive in a Nix expression, use fetchurl, which will not unpack the archive before putting it in the Nix store. This will save space, and, as we will cover in more detail later, archives are automatically unpacked during the build process in any case.

Find the replit.nix file in your repl. If you don't see it in the Files sidebar, select "Show hidden files" from the menu.

Edit replit.nix to look like this:

{ pkgs }:

let
  hello = pkgs.stdenv.mkDerivation rec {
    pname = "hello";
    version = "2.12";
    src = pkgs.fetchurl {
      url = "mirror://gnu/hello/hello-${version}.tar.gz";
      sha256 = "1111111111111111111111111111111111111111111111111111";
    };
  };
in {
  deps = [
    hello
  ];
}

Once you've made this change to replit.nix, open the Console tab, and press enter. The output should be similar to:

Nix is telling us what the hash of the file it fetched actually is, in this case: 1ayhp9v4m4rdhjmnl2bq3cibrbqqkgjbl3s7yk2nhlh8vj3ay16g. Your output might be different, that just means that you're using an updated version of Nixpkgs, so stdenv has been updated; since that's a dependency of the derivation that stdenv.mkDerivation produces and since derivation hashes depend on their input derivation hashes, your derivation's hash will have changed, too.

Now that we have the real hash, copy it to the sha256 attribute in the derivation, press enter in the console, which will then pick up on the change, and Nix will successfully build the hello package — though it won't output anything when it succeeds. The hello command will be added to your environment. If you run it, the hello program just echoes "Hello, world!" to the console. At first glance, that doesn't seem like a very useful program, but its purpose is actually to help test packaging systems. Now we know ours is working!

If you have been paying particularly close attention, you may have spotted that Nix is telling us that two derivations will be built, even though we're only asking it to build one. This is because each fetcher actually builds a derivation: the fetched file that's added to the Nix store. Nix packages can only depend on things that are in the Nix Store, so in order to build hello, we need its source code to be put in the Nix Store, too. Since we don't have it yet, it needs to be "built" first (fetched, in this case). A fetcher is actually a special type of builder.

We could also have gotten the same hash with nix-prefetch-url:

nix-prefetch-url https://ftpmirror.gnu.org/hello/hello-2.12.tar.gz

You can copy the string 1ayhp9v4m4rdhjmnl2bq3cibrbqqkgjbl3s7yk2nhlh8vj3ay16g to the sha256 field in the derivation and it will also work (again, your actual hash might be different). Sometimes the hashes are in a different format, but that's not a problem. Nix fetchers understand different types of hashes presented in a variety of formats.

Some notes on hashes

In our first example, we initially provided a hash that we knew was incorrect in order to have Nix output the correct hash in the hash mismatch error message. Trusting the hash that Nix gives back to us is an approach called trust on first use. We're assuming that the file Nix actually fetched is correct. For many purposes, this is fine.

If you have a real hash, not a dummy hash, in your derivation and you still get this error, carefully try to find out what might have happened, as this means that Nix is telling you that the file it actually fetched is not what you expected. It could be that the download was corrupted due to network problems, in which case re-attempting it later might succeed; or that the target file has actually been changed on the server. This might happen if you're trying to download from a URL that does not provide a stable version, or if an attacker has surreptitiously replaced the file. If you're unsure, try to determine with a trusted party, such as the publishers of the code, whether everything is OK.

You may notice that the hash Nix calculates for a file doesn't match the hash that sha256sum calculates. They are actually the same hash, but they're encoded differently. Most hash tools print out the hash in a hexadecimal (base 16) format, but Nix prefers its own non-standard base 32 format, because it's shorter (it's base 32, but it doesn't use the characters e, o, u, and t to reduce the chances of offensive letter sequences). To convert a base 16 hash to a base 32 hash or vice versa, use nix-hash:

$ nix-hash --to-base32 --type sha256 cf04af86dc085268c5f4470fbae49b18afbc221b78096aab842d934a76bad0ab
1ayhp9v4m4rdhjmnl2bq3cibrbqqkgjbl3s7yk2nhlh8vj3ay16g
$ nix-hash --to-base16 --type sha256 1ayhp9v4m4rdhjmnl2bq3cibrbqqkgjbl3s7yk2nhlh8vj3ay16g
cf04af86dc085268c5f4470fbae49b18afbc221b78096aab842d934a76bad0ab

You don't need to encode hashes in Nix's custom base 32 format before using them. The normal base 16 format works just fine.

Fetch Git repositories with `fetchgit`

If the source code you need is in a Git repository, you can use fetchgit. It expects at least one extra attribute compared to fetchurl, the attribute rev. This can be the full Git commit ID (the sha1 hash) or a tag name, like v2.12.

Try the following replit.nix file:

{ pkgs }:

let
  hello = pkgs.stdenv.mkDerivation rec {
    pname = "hello";
    version = "2.12";
    src = pkgs.fetchgit {
      url = "https://github.com/ritza-co/simple-hello-world-demo.git";
      rev = "v${version}";
      sha256 = "1111111111111111111111111111111111111111111111111111";
    };
  };
in {
  deps = [
    hello
  ];
}

Once again, after changing replit.nix, open the Console tab, and press enter. The output should be similar to:

Detected change in environment, reloading shell...
nix error: building nix env: exit status 102
Output has been trimmed to the last 20 lines
executing builder '/nix/store/bm7jr70d9ghn5cczb3q0w90apsm05p54-bash-5.1-p8/bin/bash'
building '/nix/store/6drp4pmqj67b3ysy88fhawz4fdf2kwkb-simple-hello-world-demo.drv'...
exporting https://github.com/ritza-co/simple-hello-world-demo.git (rev v2.12) into /nix/store/hmmp6c24wg43d9cbslmhgrrccvhhaxac-simple-hello-world-demo
Initialized empty Git repository in /nix/store/hmmp6c24wg43d9cbslmhgrrccvhhaxac-simple-hello-world-demo/.git/
remote: Enumerating objects: 462, done.
remote: Counting objects: 100% (462/462), done.
remote: Compressing objects: 100% (333/333), done.
remote: Total 462 (delta 127), reused 462 (delta 127), pack-reused 0
Receiving objects: 100% (462/462), 1.09 MiB | 7.15 MiB/s, done.
Resolving deltas: 100% (127/127), done.
From https://github.com/ritza-co/simple-hello-world-demo
 * tag               v2.12      -> FETCH_HEAD
Switched to a new branch 'fetchgit'
removing `.git'...
hash mismatch in fixed-output derivation '/nix/store/bj8zf0n8xdfrkj5mndmlhg34ac3pd91l-simple-hello-world-demo':
  wanted: sha256:1111111111111111111111111111111111111111111111111111
  got:    sha256:1mc1vrixpkzkdnvpzn3b01awvha6z7k2dnpai3c6g89in8l1wr70
cannot build derivation '/nix/store/gw50rkh9d2m4hxiyyldcz6wk0hf76pkx-hello.drv': 1 dependencies couldn't be built
error: build of '/nix/store/gw50rkh9d2m4hxiyyldcz6wk0hf76pkx-hello.drv' failed

Replacing the sha256 in the derivation with 1mc1vrixpkzkdnvpzn3b01awvha6z7k2dnpai3c6g89in8l1wr70 will allow the build to succeed (your hash might be different, check the got: sha256: line).

There are also fetchers for other version control repositories, such as fetchsvn, fetchhg, or fetchcvs.

Fetch code from GitHub with `fetchFromGitHub`

The fetchFromGitHub fetcher doesn't take a url attribute, instead replacing it with owner and repo attributes.

Try the following replit.nix file:

{ pkgs }:

let
  hello = pkgs.stdenv.mkDerivation rec {
    pname = "hello";
    version = "2.12";
    src = pkgs.fetchFromGitHub {
      owner = "ritza-co";
      repo = "simple-hello-world-demo";
      rev = "v${version}";
      sha256 = "1111111111111111111111111111111111111111111111111111";
    };
  };
in {
  deps = [
    hello
  ];
}

Again, if you switch to the Console tab and pressing enter, the build will fail because we haven't provided the correct hash. Nix will output the correct hash. Use this to get the build to succeed.

There are also fetchers for other Git forges, such as fetchFromGitLab, fetchFromBitbucket, or fetchFromSavannah. Most work just like fetchFromGitHub.

Building a package

Now that we know how to fetch source code, we need to know how to build it into actual software. Our little hello program is built in a stock-standard way, and the default options used by stdenv.mkDerivation are perfect for it. Most software is not quite so simple, and will require us to tweak some of these options.

For some common types of software, Nix has dedicated builders that make those types of software easier to build. Some examples are Python programs or C# programs.

The "standard" builder is stdenv.mkDerivation. The dedicated builders are usually wrappers around stdenv.mkDerivation, so they inherit much from it. If the software you need to build is written in C or you can't find a dedicated builder for it, use stdenv.mkDerivation to build it.

Even if there is a dedicated builder for your software, it's probably a good idea to at least read this next section on stdenv.mkDerivation so you understand the fundamentals of building a package in Nix.

Building with `stdenv.mkDerivation`

So far, we've not really explained what a derivation means in Nix. A derivation is an attribute set that tells Nix what it needs to know to build a package.

It contains information about:

What other derivations, if any, a derivation depends on;
What build script to use;
What platform to build for;
What arguments and environment variables should be available to the builder; and
Where Nix should put the results of the build.

As the final part of evaluating a Nix expression that produces a derivation, Nix will save that derivation attribute set to disk in the Nix store as a .drv file. It represents the build action. Later, in the build phase, Nix will use this .drv file to build the package it describes. If you want to see what one looks like, run the following command in the Console:

nix show-derivation $(which hello)

This will show you hello's derivation file, which was used by Nix to build it.

Before Nix builds a derivation, it will ensure that all the input derivation paths are valid. That is, that those derivations have been built and their outputs exist in the Nix store. If not, it will fetch them from the binary cache, or build those first.

Nix actually has a built-in function called derivation that produces derivation attribute sets, but we usually use stdenv.mkDerivation instead, which is easier to use. The stdenv.mkDerivation builder is not built into the Nix language itself. It's part of Nixpkgs, and evolved over time as the community built more and more packages, incorporating their learnings as useful abstractions.

The minimum attributes that stdenv.mkDerivation needs are name and src. If name is not provided, it will attempt to construct it from pname + version: "${pname}-${version}".

The stdenv.mkDerivation builder automates common build tasks and provides common Unix tools: gcc, coreutils/findutils/diffutils, sed/grep/awk, tar/gzip/bzip2/xz, make, bash, and patch. If your package uses the Unix standard ./configure; make; make install build procedure (like our earlier hello example), you don't even need to tweak the standard build at all. If stdenv.mkDerivation doesn't work automatically, you can easily customize or override the various build phases.

Let's take a look at a more complex derivation:

{ pkgs }:

let
  mle = with pkgs; stdenv.mkDerivation rec {
    pname = "mle";
    version = "1.5.0";

    src = fetchFromGitHub {
      owner = "adsr";
      repo = "mle";
      rev = "v${version}";
      sha256 = "1nhd00lsx9v12zdmps92magz76c2d8zzln3lxvzl4ng73gbvq3n0";
    };

    # Bug fixes found after v1.5.0 release
    patches = [
      (fetchpatch {
        name = "skip_locale_dep_test.patch";
        url = "https://github.com/adsr/mle/commit/e4dc4314b02a324701d9ae9873461d34cce041e5.patch";
        sha256 = "sha256-j3Z/n+2LqB9vEkWzvRVSOrF6yE+hk6f0dvEsTQ74erw=";
      })
      (fetchpatch {
        name = "fix_input_trail.patch";
        url = "https://github.com/adsr/mle/commit/bc05ec0eee4143d824010c6688fce526550ed508.patch";
        sha256 = "sha256-dM63EBDQfHLAqGZk3C5NtNAv23nCTxXVW8XpLkAeEyQ=";
      })
    ];

    # Fix location of Lua 5.4 header and library
    postPatch = ''
      substituteInPlace Makefile --replace "-llua5.4" "-llua";
      substituteInPlace mle.h    --replace "<lua5.4/" "<";
      patchShebangs tests/*
    '';

    # Use select(2) instead of poll(2) (poll is returning POLLINVAL on macOS)
    # Enable compiler optimization
    CFLAGS = "-DTB_OPT_SELECT -O2";

    nativeBuildInputs = [ makeWrapper installShellFiles ];

    buildInputs = [ pcre uthash lua5_4 ];

    doCheck = true;

    installFlags = [ "prefix=${placeholder "out"}" ];

    postInstall = ''
      installManPage mle.1
    '';
  };
in {
  deps = [
    mle
  ];
}

This was adapted from mle's derivation in Nixpgks. Let's break down some of the new concepts in here.

Dependencies

If your software depends on other packages that are not part of the standard environment, you can provide them using the buildInputs attribute as follows:

pkgs.stdenv.mkDerivation {
  name = "foo-1.2.3";
  ...
  buildInputs = with pkgs; [libbar perl ncurses];
}

You may also see nativeBuildInputs, which you can think of as being for build-time dependencies, whereas buildInputs is for run-time dependencies. That is an oversimplification, but it's a good approximation.

If you're unsure where to put a dependency, use buildInputs. Even if you accidentally put a build-time dependency there, the derivation should still build. It's not ideal, but if you're just trying to get some software into your repl, it'll do just fine.

There are even more ways to specify dependencies, but unless you're cross-compiling they're unlikely to matter to you.

Patches

One of the great things about Nix is that since it's source built, it has first-class support for applying patches to software.

pkgs.stdenv.mkDerivation {
  name = "foo-1.2.3";
  ...
  patches = [
    (fetchpatch {
      url = "https://example.com/patches/001_arches_align.patch";
      sha256 = "0i3qclm2mh98c04rqpx1r4qagd3wpxlkj7lvq0ddpkmr8bm0fh0m";
    })

    (fetchpatch {
      url = "https://example.com/patches/002_no_remove_static_const.patch";
      sha256 = "0zfjqmjsj0y1kfzxbp29v6nxq5qwgazhb9clqc544sm5zn0bdp8n";
    })

    (fetchpatch {
      url = "https://example.com/patches/003_64_bit_clean.patch";
      sha256 = "0mda9fkaqf2s1xl6vlbkbq20362h3is9dpml9kfmacpbifl4dx3n";
    })
    ];
}

Patches are applied in the order that they are listed. They must be in the format accepted by the patch command, and may optionally be compressed using gzip, bzip2, or xz.

They can be local files, or you can fetch them. Prefer using fetchpatch rather than fetchurl to fetch patches. It works similarly, but it performs normalization on the patches before computing the hash, such as removing comments and unstable parts sometimes added by version control systems that change over time (and which would otherwise cause the hash to change).

Environment variables

Any attributes that you set on stdenv.mkDerivation will also be made available in the build environment as environment variables. Be aware that they'll be set in all phases if you set them this way.

Build phases

The standard builder script has several phases, which are defined as bash functions. You can influence the behaviour of each phase by setting specific attributes on stdenv.mkDerivation, some of which are detailed below. The most common phases are as follows, in order:

unpackPhase: This should unpack the source into the current directory. The default implementation simply unpacks the derivation's src files.
- By default it supports plain tar archives, or those compressed by gzip (*.tar.gz, *.tgz or *.tar.Z), bzip2 (*.tar.bz2, *.tbz2 or *.tbz) or xz (*.tar.xz, *.tar.lzma or *.txz).
- It can also automatically unpack zip files. Zip files are unpacked using the unzip package, which is not in the standard environment. Add it to nativeBuildInputs.
- Setting dontUnpack to true will skip this phase.
patchPhase: The patch phase applies any supplied patches to the unpacked source code.
- patchFlags sets flags to be passed to patch. If not set, the argument -p1 is used, which causes the leading directory component to be stripped from the file names in each patch.
- Setting dontPatch to true skips this phase, but if patches is not set it's also skipped.
configurePhase: Prepares the source tree for building. By default, it runs ./configure if it exists.
- Set configureScript to change the configure script. Defaults to ./configure.
- Set configureFlags to pass additional arguments to the configure script.
- By default, --prefix=$prefix is added to the configure flags. Set dontAddPrefix to disable this.
- Set prefix to set the $prefix variable above (remember how attributes defined here are also exposed as environment variables). By default this is set to $out, which is the output directory that Nix creates for your package in the Nix store.
- Setting dontConfigure to true will skip this phase.
buildPhase:
- Set makeFile to change the name of the MakeFile.
- Set makeFlags to pass additional flags to make.
- Set buildFlags to pass additional flags to make, but only called during the build phase.
- Setting dontBuild to true will skip this phase.
installPhase:
- Set installFlags to pass additional flags to make, that will only be called during the install phase.
- Remember that makeFlags will also affect this phase.
- Setting dontInstall to true will skip this phase.

You can override any of these phases by setting an attribute with the phase's name. It will be executed as a bash script in the standard environment.

You can also adjust the build by running code before and after each phase. Set at attribute with either pre or post and the phase's name (capitalized), e.g. preConfigure or postBuild.

You can add yet more phases before or after each of these phases, or even reorder them completely. Read the documentation for build phases for details on how to do that.

Here we've covered the basics. Read stdenv.mkDerivation's documentation for more. Remember that this is the basis for the largest software repository, and as such there's a lot it is capable of.

Shell functions and utilities

The standard environment also has a few shell functions and utilities that may be helpful if you're making adjustments to the phases above, such as:

substituteInPlace, which performs substitutions in files, especially handy to replace references in scripts to executables in nix derivations to get them to work correctly:

  substituteInPlace ./foo.sh \
    --replace /usr/bin/bar $bar/bin/bar \
    --replace /usr/bin/baz $bar/bin/baz

Dedicated builders

As we touched on before, stdenv.mkDerivation is not the only builder. Many frameworks, programming languages, or build systems have dedicated builders that provide conveniences and abstractions for their idiosyncrasies. Be sure to have a look at builders for specific languages and frameworks in the Nixpkgs manual.

It is not necessarily an exhaustive list. Even if you don't see a dedicated builder for your use case listed in the manual, there may still be one. The best way to find out is to have a look at source code in Nixpkgs, which is hosted on GitHub.

Look for terms, tools, and commands that are specific to your ecosystem. You can use GitHub's web search, or make a local clone of the repo to grep (consider making a shallow clone using git's --depth=1 flag, as it's quite a big repository with many branches and a long history).

Package setup hooks

Hooks are scripts that are run during the build if a dependency uses them. If a dependency of your derivation uses a hook, that hook will be run during the build of your derivation.

You should not use hooks directly, but be aware that depending on packages that use hooks may change the way your build works. Even stdenv.mkDerivation includes some hooks, for example, to place docs in the right place, to remove debug symbols, or to compress man pages.

There are hooks for specific technologies, for example, the cmake derivation uses the cmake hook, which makes some changes to stdenv.mkDerivation for Cmake projects. Thus, including cmake (the derivation) in the nativeBuildInputs of your derivation will change the way it works. You can use the cmakeFlags attribute in this situation.

Learning HTML and CSS by building a 90s-inspired website

RitzaCo — Thu, 25 Aug 2022 09:47:00 +0000

In this tutorial, we will make a 90s-inspired website using HTML and a little CSS.

Nineties web design is pretty iconic. With backgrounds that can make your eyes water, animated GIFs and cursors, and an overload of text, graphics, and ads, there is only one word to describe 90s web design - garish!

Yet for those who witnessed the birth of the world wide web, 90s web design brings back fond memories.

As most of the websites built in the 90s didn't require complicated CSS and JavaScript, building a 90s-inspired website can be a fun first project to learn web development.

HTML and CSS

Every website you see on the web has two main building blocks: HTML and CSS.

Hyper Text Markup Language (HTML) is not a programming language. It is, as the name suggests, a markup language. To understand what a markup language is, we need to travel back in history.

Imagine you are an editor in the olden days and you receive a manuscript to revise. You want to write a bunch of revision instructions for the author on the manuscript. Or you may want to write instructions for the copy editor (write certain lines in a bigger font, make certain words bold, and so on).

To keep your instructions distinct from the content of the manuscript itself, you grab a red or blue pencil and write your instructions. In other words, you "mark up" the manuscript.

Fast forward to the electronic age. You are a website developer. You want your website to look a certain way. You need to "mark up" the content for the browser, which is responsible for displaying the content on the screen.

Enter HTML!

Rather than marking up our content with red and blue pencils, we will break our content into elements and wrap each element inside an opening and closing HTML tag.

HTML is a markup language that defines the structure of your content. HTML consists of a series of elements, which you use to enclose, or wrap, different parts of the content to make it appear a certain way, or act a certain way. The enclosing tags can make a word or image hyperlink to somewhere else, can italicize words, can make the font bigger or smaller, and so on. ~ MDN

HTML tags are written using angle brackets, like these: < >. A closing tag also has a forward slash: </ >.

Let's say we have some text:

I love 90s design

And we want to instruct the browser to display this text as a heading. We can simply wrap the text between the opening and closing tags, like so:

<h1>I love 90s design</h1>

There are tons of HTML elements. But don't worry! You don't have to memorize everything. Once you understand how elements and tags work, you can always refer to the documentation and find relevant elements and their usage.

HTML is the skeleton of our website. But CSS or Cascading Style Sheets is what adds interest to a website. CSS is used to style and alter the layout of HTML elements. We use CSS to specify fonts, change colors and size, add animations, and control other decorative features of our website.

We will learn more about HTML and CSS as we make our website.

Getting started

In this tutorial we are going to use Replit to make our website. The cool thing about Replit is that you don't need to install anything. All you need is a computer with a browser and internet connection.

Create an account on Replit if you haven't already. Create a new Repl and choose HTML, CSS, JS from the template dropdown.

You will see that we have three files added to our project. The index.html file is where we will write our HTML. The style.css file is where we will write our CSS. You can delete the script.js file, as we won't write any JavaScript in this tutorial.

Replit prepopulates the index.html file with a bunch of code. Delete everything in there as we will start from scratch.

Copy the following line in your index.html file, and you will see it formatted as a heading in the browser preview window:

<h1>Web Design in the 90s</h1>

That's it! You just made your very own web page 🎉🎉🎉

Building structure

While writing individual HTML tags does work, to create a real website we need to combine individual elements in a structured way. We will also need to add some extra information and metadata about our site for SEO and other purposes.

In your code editor, erase everything.

The very first piece of HTML we will write is <!DOCTYPE html>.

<!DOCTYPE html>

The <!DOCTYPE html> tag is a doctype tag. It is a required tag that is added at the top of all HTML documents. This tag makes sure everything behaves as expected. Note that there is no closing tag as we are not wrapping this tag around any content.

Next we will add an <html> element:

<!DOCTYPE html>
<html lang="en-US"></html>

The <html> tag wraps around all the content and is often called the root element. This tag tells the browser that everything enclosed inside this tag is HTML. HTML elements can also be nested inside each other. All further elements we add will be nested inside the <html> element.

Also, notice how we set the language to USA English by setting the value of the lang attribute to "en-US". We can pass extra information to an HTML element using attributes.

The `<head>` element

Inside the <html> element, the content is divided into a <head> element and a <body> element.

<!DOCTYPE html>
<html lang="en-US">
  <head> </head>

  <body></body>
</html>

The head element is a container where we include all the meta information. We can also include extra information about the website, which we don't want to render, or show, on the website itself. This extra information can include data to improve our website's SEO ranking, links to other files, and so on.

Let's add these elements to the <head>:

<!DOCTYPE html>
<html lang="en-US">
  <head>
    <meta charset="utf-8" />
    <title>My 90s website</title>
  </head>

  <body></body>
</html>

To display an HTML page correctly, a web browser must know which character set to use. Adding the line <meta charset="utf-8"> tells our browser to use the UTF-8 character set. UTF-8 is the recommended character set as it covers almost all of the characters and symbols in the world!

The <title> element contains the title of our website. This title appears in the browser tab. It is also used to describe the page when you bookmark it.

Tip
In Replit you can generate this boilerplate code by typing ! followed by the tab key in an empty HTML file.

The `<body>` element

Everything we want to display on our website will be nested within the <body> element. We will spend most of our time as web developers in this element.

Let's add a <header> element and a heading to the <body> of our site:

<!DOCTYPE html>
<html lang="en-US">
  <head>
    <meta charset="utf-8" />
    <title>My 90s Website</title>
  </head>
  <body>
    <header>
      <h1>My 90s Website</h1>
    </header>
  </body>
</html>

The <header> element usually contains introductory and/or navigational content. Don't confuse the <header> with the <head> element.

The <h1> element is the level one heading element. Heading elements allow us to specify that certain parts of our content are headings or subheadings. There are six heading levels in HTML, <h1> to <h6>.

Info Indentation

The indentation in the HTML code is not required. The only reason we indent our code is to make it easier to read.

Adding more content

Let's add some more content to our site. We already have a heading, so let's add a <main> element to our web page:

<body>
  <header>
    <h1>My 90s Website</h1>
  </header>
  <main></main>
</body>

The <main> element represents the dominant content of the body of a document.

Next we will add some text or paragraph elements:

<body>
  <header>
    <h1>My 90s Website</h1>
  </header>
  <main>
    <p>
      This is a <strong>90s inspired</strong> website. Today, 90s web design is
      more likely to raise a smile than admiration.
    </p>
    <hr />
    <p>
      See what Apple, Microsoft, Yahoo or Pepsi websites looked like in the
      mid-1990s.
    </p>
  </main>
</body>

We have added two paragraph elements under the heading. According to the documentation:

The <p> HTML element represents a paragraph. Paragraphs are usually represented in visual media as blocks of text separated from adjacent blocks by blank lines and/or first-line indentation, but HTML paragraphs can be any structural grouping of related content, such as images or form fields.

We have also wrapped the text "90s inspired" with the <strong> tag. The <strong> element indicates that its contents have strong importance. The browser will render the contents of <strong> element in bold type.

Also, notice the <hr> element which is adding a horizontal separator between the two paragraphs. There are certain elements like the <hr> element that do not require a closing tag as they do not wrap around any content.

Tip

Which other element have we used that didn't require a closing tag?

Hit the "Run" button on your Replit site and you will see the new text appear in the browser preview window.

Adding links

Next, we will add a link to the web design museum so our readers can see some actual 90s websites. We want to make some of our text clickable. We can do that by using the anchor tag <a>.

First wrap the text that you want to make clickable with the <a></a> tags, like so:

<p>
  See what Apple, Microsoft, Yahoo or Pepsi websites
  <a>looked like in the mid-1990s</a>.
</p>

The anchor element requires an href or hyperlink reference attribute, which is the URL that the hyperlink points to.

<p>
  See what Apple, Microsoft, Yahoo or Pepsi websites
  <a href="https://www.webdesignmuseum.org/exhibitions/web-design-in-the-90s"
    >looked like in the mid-1990s</a
  >.
</p>

Hit "Run" and you should see the link in action:

Adding images

You can't have a 90s-inspired website without the animated GIF of the dancing baby!

Create a new folder in the "Files" section in your repl, and name it "img". Download the images from here and upload them to the "img" folder.

Images are added with an image element <img>. Inside this tag we need to give the image location, or source, with a src attribute, like so:

<img src="img/dancing-baby.gif" />

We will add the image within the <header> element. We will also add a description of the image with an alt attribute:

<body>
  <header>
    <h1>My 90s Website</h1>
    <img src="img/dancing-baby.gif" alt="Animated GIF of a dancing baby" />
  </header>
  <main>
    <p>
      This is a <strong>90s inspired</strong> website. Today, 90s web design is
      more likely to raise a smile than admiration.
    </p>
    <hr />
    <p>
      See what Apple, Microsoft, Yahoo or Pepsi websites
      <a
        href="https://www.webdesignmuseum.org/exhibitions/web-design-in-the-90s"
        >looked like in the mid-1990s</a
      >.
    </p>
  </main>
</body>

This is how our website looks:

The `<div>` element

The <div> element is like an empty box. We can use it when we need to break the content on our website into different sections, to control styling, and more.

For our site, we will use the <div> element to add a background image to our site later.

Let's add a new <div> element to our "index.html" file and nest everything else inside it:

<body>
  <div><!-- This is the new addition. -->
    <header>
      <h1>My 90s Website</h1>
      <img src="img/dancing-baby.gif" alt="" />
    </header>
    <main>
      <p>
        This is a <strong>90s inspired</strong> website. Today, 90s web design
        is more likely to raise a smile than admiration.
      </p>
      <hr />
      <p>
        See what Apple, Microsoft, Yahoo or Pepsi websites
        <a
          href="https://www.webdesignmuseum.org/exhibitions/web-design-in-the-90s"
          >looked like in the mid-1990s</a
        >.
      </p>
    </main>
  </div><!-- Don't forget to close the div element -->
</body>

Info Comments

The  characters mark a comment. Anything written between these two tags will be ignored by the browser. We add comments to explain our code to other humans.

Linking files

The website has all the content that we need. Now it's time to add some CSS magic.

Before we write any CSS, we need to leave instructions for our browser so it knows where to look for our CSS file.

To link the CSS file to the HTML file, we will use a link element <link>. The <link> element is used to specify relationships between the current document and an external resource. This element is most commonly used to link to CSS, but it can be used to link other files.

We will add the <link> element within the <head> element of our site:

<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <link rel="stylesheet" href="style.css" />
  <title>My 90s Website</title>
</head>

The <link> element needs a rel or relationship attribute and an href attribute. We set the rel attribute to "stylesheet" to tell our browser what kind of document are we linking. We will add the name of our stylesheet as the value of the href attribute.

Info

If your CSS file is in another folder or directory, you will need to provide the complete path to the CSS sheet.

Notice we have also added a new <meta> tag. This gives the browser instructions on how to control the page's dimensions and scaling. You can read more about it on MDN documentation.

Basic styling

In our CSS file, we can list the HTML elements we’ve used and say how we want them to look. We use CSS properties and values to control the look of our elements.

There are many ways to point to the elements we want. The easiest way is to use the element's name.

For example, the following code will select the <body> element, and change its background-color property to black:

body {
    background-color: black;
}

You can also select multiple elements at once. For example, the following code will change the text color of both <h1> and <p> elements:

h1, p {
    color: blueviolet;
}

We can also declare more than one rule at once. For example, the following group of rules will alter the size and the extra spacing (padding) at the top of our <h1> elements:

h1 {
    font-size: 4rem;
    padding-top: 10rem;
}

There are a lot of CSS properties. Covering them all is beyond the scope of this tutorial. You can look up all the CSS properties on MDN documentation.

Another good way to find CSS properties and their values for your use case is searching for them using your favorite search engine. For example, if we want to learn how to align the text on our web page to the center, we can search "CSS text align".

The first result was this MDN page which explains the usage of text-align property. Add this new property to your code:

body {
    background-color: black;
    text-align: center;
}

Tip

A good way to learn CSS is by playing around with different properties and their values.

HTML classes

Selecting elements by name comes in handy when we want to select all elements of the same type on a page at once. But for better control, we may want to select and make changes to individual elements. One way to select individual elements is using classes.

HTML classes are attributes that we can add to elements. Once an element has a class name, we can use this in our CSS. You can think of classes as custom labels that we attach to our elements.

Let's add a class bigger-text to our first <p> element:

<p class="bigger-text">
  This is a <strong>90s inspired</strong> website. Today, 90s web design is more
  likely to raise a smile than admiration.
</p>

Naming the classes is totally up to you. You can name the classes whatever way you want. But it's a good practice to give classes a descriptive name.

In our style.css file we can select the element with the class bigger-text. To tell the CSS that we are selecting a class, and not a built-in HTML element, we have to add a dot . before the class name. For example, we can select the bigger-text class and change its fonts to a different size like so:

.bigger-text {
  font-size: 1.5rem;
}

Info

CSS has several different units for expressing length. We are using a relative size unit rem here. But we can also use absolute units like px, which stands for pixels.

Let's also add a class container to our <div> element and use it to add a background image:

<body>
  <div class="container">
    <header>...</header>
    <main>...</main>
  </div>
</body>

Upload the window.png file to your image folder, if you haven't already. Now add the following CSS code to your style.css file:

.container {
  background: url("img/window.png");
  background-position: center;
  background-repeat: no-repeat;
  background-size: contain;
  height: 800px;
  width: 800px;
  margin: auto;
}

CSS properties are pretty self-explanatory. In the code above, we use an image as a background with a url() function. This is just like passing the URL of an image to the href attribute in HTML.

Next, we tell the browser to position this image in the center and not to repeat it multiple times. We also set the height and width. This time we use absolute length units px.

The margin property controls the extra space around an element. Setting it to auto means we want equal space all around an element, which is a good way to center an element.

Let's add our emoji image to the body element to make our website as eye-watering as possible 😀

body {
  background: black url("img/emoji.png");
  text-align: center;
}

Notice we changed the background-color property to background and added both a color and an image to it in a single line.

Also notice that this time we didn't use the background-repeat: no-repeat which resulted in our image repeating multiple times to fill the whole body element.

Custom domain

Our website is done! We can share it with the world by sharing the URL of our repl.

There is one problem, however. The URL is not very reader-friendly. We want something easier like "ilove90sdesign.com".

There are many places you can buy a custom URL or domain. Some of them are Google Domains, GoDaddy, and Namecheap.

Let's walk through the process of connecting our repl to a custom domain from Namecheap.

Buy a domain on Namecheap.

Next, in your Replit site, click on the pencil icon in the browser preview window and click on "Create Domain Link". Enter your domain and the domain linking window will open:

Copy the IP address from the "Domain Linking" dialog.

Sign in to your Namecheap account. Follow the instructions from step 3 of this guide. Select "@" for "Host" and enter the IP address that you have copied above in the "IP Address" field.

Click "Save changes". Back in your Replit site, click the "Next" button. Replit will verify the domain and you are done!

Note

It can take some time before the changes take effect.

Where next?

That's it for this tutorial, but you can build your site further. Try adding more sections to your website, or play around with CSS properties and selectors to give your site a different look.

You can find our repl below:

https://replit.com/@ritza/My-90s-website

Phaser vs PixiJS for making 2D games

RitzaCo — Thu, 18 Aug 2022 07:53:00 +0000

Phaser and PixiJS are popular open-source JavaScript WebGL libraries that are used to create 2D browser games. They render graphics inside an HTML canvas element. Games can be developed using JavaScript or TypeScript. These libraries use WebGL for creating high-performance, complex visual effects. You can create simple browser games using vanilla JavaScript, but if you want to have performant rendering or advanced features in your game such as physics or realistic lighting, vanilla JavaScript is not a good choice. These libraries speed up game development by providing useful functionality and they improve performance.

Let's compare Phaser and PixiJS for making 2D games. We'll use code snippets of a simple version of Flappy Bird, created using each library, as practical examples of the differences and similarities between the two libraries.

Here are the links to the Flappy Bird games:

To move the bird, press up, click or touch the screen. There is no restart; you'll need to refresh the page to play again.

Here are the links to the code for the Flappy Bird games:

Phaser basics

Phaser is a beginner-friendly 2D game framework that is used to create HTML5 games. It uses WebGL for rendering, and it has a Canvas fallback for when WebGL is not supported. It has all the functionality that you need to build a game. Its features include:

A pre-loader to load game assets such as images and sounds.
Three physics systems to choose from. They allow you to add gravity and collision detection to games.
Animation, including animation using sprite sheets.
A particle system for creating effects such as moving stars.
User input functions to control user input.
Sound: Web Audio with legacy HTML Audio support.
Scale Manager to control responsive game layout.
Multi-camera support.
Plugin system for extra functionality.

To see some examples of games created using Phaser, check this link.

The following code example shows the basic structure of a Phaser game:

const config = {
  type: Phaser.AUTO,
  width: 800,
  height: 600,
  physics: {
    default: "arcade",
    arcade: {
      gravity: { y: 500 },
      debug: true,
    },
  },
  scene: {
    preload: preload,
    create: create,
    update: update,
  },
};

const game = new Phaser.Game(config);

function preload() {}

function create() {}

function update() {}

To make a game, a Phaser.Game instance is created and a config object is passed in as an argument. There are many configuration options available; this example only shows a few of them. The type property is the rendering context, the recommended value is Phaser.AUTO. This uses WebGL for rendering and if the browser or device does not support it, it uses Canvas as a fallback.

Three functions are used to create a game scene and update it:

preload() - Load assets such as images and sounds.
create() - Set up a scene: create sprites and position them. Set up user input event listeners and collision detection.
update() - Game loop: update the scene on every frame. For example, moving sprites and checking their current position.

PixiJS basics

PixiJS is a fast, lightweight 2D graphics library that is used to create interactive graphics and games. It's not a game framework; it's a library for 2D rendering. It does not have many of the built-in game functions that Phaser has, such as collision detection. To create a game, you need to build a lot of the game functionality yourself, unless additional libraries are used. The features of PixiJS, which focus on rendering graphics, include:

Asset loader to load assets such as images, fonts and animation data.
Animation, including animation using sprite sheets.
Tinting and blending modes.
WebGL filters and shaders.
Accessibility: All content can easily be made to be screen-reader accessible.

To see some examples of 2D graphics created using PixiJS, check this link.

The following code example shows the basic structure of a PixiJS game:

const app = new PIXI.Application({
  width: 800,
  height: 600,
  antialias: true,
  transparent: false,
  resolution: 1,
});

document.body.appendChild(app.view);

app.loader.add("assets/images/cat.png").load(setup);

function setup() {
  // Using a game state helps modularize your code
  state = play;

  // Start the game loop
  app.ticker.add((delta) => gameLoop(delta));
}

function gameLoop(delta) {
  // Update the current game state
  state(delta);
}

function play(delta) {
  // The game logic goes here
}

function end() {
  // All the code that should run at the end of the game
}

// Add your game helper functions:
//   such as a collision detecting function

To make a game, a PIXI.Application instance is created and an options object is passed in as an argument. The options are the optional renderer parameters such as the width and height of the renderer's view. The renderer uses the canvas element, app.view, that PixiJS automatically creates for you. It is added to the HTML document using the appendChild method. The assets for the game are loaded using the loader instance. This is like the preload function used in Phaser. Once the assets are loaded, the setup function is called.

Four functions are used to create a game scene and update it, after the game assets are loaded:

setup() - Set up a scene: Create sprites and position them. Set up user input event listeners and collision detection. Set up the game state and start the game loop. The method ticker.add starts the gameLoop.
gameLoop() - Update the scene on every frame. The play() function is called to handle the game logic.
play() - Handle game updates, for example moving sprites and checking their current position.
end() - All the code that should run at the end of the game, such as changing the game state.

Documentation and ease of use

Phaser and PixiJS have good documentation for their APIs. They also provide examples and tutorials for making games. Phaser has more game-specific examples, whereas the PixiJS examples focus on graphics rendering. It is easier to make a game using Phaser as it is a game framework. It provides useful functionality for games and the code structure is more organized for games by default. PixiJS is less opinionated about how you structure a game.

When you publish a game, it's best to bundle your files to make them as small as possible. Both Phaser and PixiJS provide starter templates to bundle your game using Webpack.

Adding game physics

Phaser comes with built-in game physics, whereas PixiJS does not. Phaser has three types of built-in physics: Arcade Physics, Impact Physics, and Matter.js. For example, if you wanted to add Arcade Physics, which has dynamic and static bodies, you add it to the config as can be seen in the code example in the Phaser basics section above. A dynamic body is a body that can move around via forces such as velocity and acceleration. These bodies can bounce and collide. There is also a debug property that, when set to true, displays the outline of physics bodies and shows the effect of forces as can be seen in the Phaser Flappy Bird game. There is a performance cost in drawing debug displays. It should not be used in production. The gravity property allows us to set up the gravitational force.

The collider method is used to detect a collision between the bird and the pipes in the Flappy Bird game:

collider = this.physics.add.collider(bird, pipes, collisionCallback);

The collisionCallback function is run when a collision is detected. It can be used to run all of the code that should run when the game is over:

function collisionCallback() {
  gameOver = true;
  collider.active = false; // turn off so that the bird falls to the ground on collision
  bird.setFlipY(true);
  game.sound.play("crashSound");
}

Setting up physics in PixiJS requires building the gravity and collision detection yourself. Making the bird fall in Flappy Bird by simulating gravity with PixiJS only requires two lines of code added to the play() loop:

bird.vy += 0.25;
bird.y += bird.vy;

The bird's velocity is increased on each game loop and then its y position is updated. Collision detection requires writing your own collision detector, for example the hitTestRectangle function in the PixiJS Flappy Bird game.

Another option is to add a third-party physics library such as Matter.js, although setting up and integrating the physics library can be tricky. If you need physics in your game, especially more complex physics effects, Phaser is a better choice.

Adding animation

PixiJS and Phaser have basic animation functionality for sprite sheet animation, tweens for smooth animation and they have particle systems to create effects such as an explosion. The particle system needs to be installed as a separate library for PixiJS.

For more advanced graphics effects, PixiJS is a better choice as it includes many examples of how to create advanced graphics features such as WebGL filters and shaders. The PixiJS website shows some real-world examples of websites that were created using PixiJS. It has also been used by many well-known global brands.

Adding user input

Phaser provides many methods to handle user input, including more advanced use cases such as drag and drop. PixiJS requires more manual setup of user input. For example, in the Phaser Flappy Bird game, making the bird fly up when the user presses the up arrow, clicks the screen or touches the screen requires three lines of code.

In the create function, the createCursorKeys method creates and returns an object containing four hotkeys for up, down, left, and right as well as space bar and shift:

cursors = this.input.keyboard.createCursorKeys();

In the update function, we listen for an arrow up press, a mouse click or a screen touch and then move the bird up.

if (cursors.up.isDown || this.input.activePointer.isDown) {
    bird.setVelocityY(-200);

To make the bird move up in the PixiJS Flappy Bird game requires a lot more code. A keyboard helper function is created, which is used in the setup function to listen for the specific input events and set the bird's velocity when the event occurs.

Implementing a responsive layout

Browser games can be played on desktop or mobile devices; they may also be compiled to native mobile apps by using third-party tools such as Cordova. It's important that your 2D game has a responsive layout. Phaser has a Scale Manager that handles scaling, resizing, and alignment; it also has a full-screen mode. When using PixiJS, you need to create a responsive layout manually. This can be tricky with more complex layouts.

Let's compare the responsive layout implementation of the Phaser and PixiJS Flappy Bird games. For both games, the game canvas width is set at 800px, the height is set at 600px and it is centered in the window. The canvas is scaled to fill the browser window as much as possible while maintaining its aspect ratio.

In the Phaser implementation, this requires setting some scale properties in the config:

  scale: {
    mode: Phaser.Scale.FIT,
    autoCenter: Phaser.Scale.CENTER_BOTH,
    width: CONFIG_WIDTH,
    height: CONFIG_HEIGHT,
  },

In the PixiJS implementation, this requires more code. In the setup function, a "resize" event listener was created with a callback function called resize:

window.addEventListener("resize", resize);

// call it manually once - make sure the stage is correctly sized on page load
resize();

The resize function is a helper function that determines the current screen size and what scale factor is needed to make the game canvas fill the screen while maintaining its aspect ratio. It then uses the scale factor to change the CSS styling of the game canvas to scale the canvas size up or down:

function resize() {
  // current screen size
  const screenWidth = Math.max(
    document.documentElement.clientWidth,
    window.innerWidth || 0
  );
  const screenHeight = Math.max(
    document.documentElement.clientHeight,
    window.innerHeight || 0
  );

  // scale factor for our game canvas
  const scale = Math.min(
    screenWidth / CONFIG_WIDTH,
    screenHeight / CONFIG_HEIGHT
  );

  // scaled width and height
  const enlargedWidth = Math.floor(scale * CONFIG_WIDTH);
  const enlargedHeight = Math.floor(scale * CONFIG_HEIGHT);

  // margins for centering
  const horizontalMargin = (screenWidth - enlargedWidth) / 2;
  const verticalMargin = (screenHeight - enlargedHeight) / 2;

  // CSS to set the sizes and margins
  app.view.style.width = `${enlargedWidth}px`;
  app.view.style.height = `${enlargedHeight}px`;
  app.view.style.marginLeft = app.view.style.marginRight = `${horizontalMargin}px`;
  app.view.style.marginTop = app.view.style.marginBottom = `${verticalMargin}px`;
}

Adding sounds

Both Phaser and PixiJS provide support for sound functionality. They provide a beginner-friendly interface for the Web Audio API. Phaser also supports legacy HTML Audio. For PixiJS, the PixiJS Sound library needs to be added. This library is a Web Audio API playback library that is built for modern browsers. It has a small bundle size (8.7 kB minified and GZipped) with no dependencies and is tree-shakable so you can remove unused modules in your production build.

Let's compare how sound was added to the Phaser and PixiJS Flappy Bird games. You'll see that the implementation is similar.

In the Phaser Flappy Bird game, the "woosh" sound that the bird makes when it moves up is loaded into the game in the preload function:

this.load.audio("birdSound", "./assets/sounds/woosh.mp3");

The sound.play method is called to play the bird sound:

game.sound.play("birdSound");

In the PixiJS Flappy Bird game, the PixiJS Sound library is imported using a script tag in the index.html file:

<script src="https://unpkg.com/@pixi/sound/dist/pixi-sound.js"></script>

The sound is loaded into the game using the add method in the script.js file:

.add("bird-sound", "assets/sounds/woosh.mp3")

The sound.play method is called to play the bird sound:

PIXI.sound.play("bird-sound");

Bundle size comparison

The Flappy Bird game examples import the libraries using a <script> tag for ease of use. When building a production-ready game, you can use the Webpack starter templates that are available for each of the libraries to bundle the game files so that the file size is as small as possible. To compare the bundle sizes, the two Flappy Bird games were bundled using the following Webpack starter templates:

Phaser Webpack starter template
PixiJS TypeScript Webpack starter template: TypeScript was disabled using // @ts-nocheck

The following table compares the bundle sizes. The bundle size of PixiJS is less than half the size of the bundle size of Phaser.

	Phaser	PixiJS
npm package minified bundle size	1 MB	478.6 kB
npm package minified and GZipped bundle size	274.1 kB	125.4 kB
Flappy Bird game minified bundle size	1.02 MB	424 kB

PixiJS is also tree-shakable, so you can remove unused modules in your production build. This will further reduce the bundle size. The PixiJS Flappy Bird game includes the PixiJS Sound library. The Flappy Bird game bundle size can be further reduced in the browser using GZip compression.

If bundle size is critical, for example if you are building a mobile game for users with a poor internet connection, then PixiJS is a good choice, as long as you are willing to build a lot of the game functionality yourself.

Conclusion - which one is the best?

The following table shows a comparison between Phaser and PixiJS for 2D browser game development. It shows which library is the best for each category.

	Phaser	PixiJS
Beginner-friendly	✔️
Documentation	✔️	✔️
Game physics	✔️
Animations / visual effects		✔️
Handling user input	✔️
Responsive layout	✔️
Sounds	✔️	✔️ *
Bundle size		✔️
Accessibility		✔️

* needs an extra library

Phaser is a framework for making games and is more beginner-friendly than PixiJS. If you compare the code for the Phaser and PixiJS Flappy Bird games, you'll see that the number of lines in the PixiJS implementation is more than double the number of lines in the Phaser implementation. This is because some functionality such as collision detection and containing the bird in the visible area of the game canvas required creating custom functions.

PixiJS can also be good for beginners looking to understand game development more deeply as they will have to implement a lot of functionality themselves.

For more complex games, Phaser is a better choice because of the built-in game functionality. Although you can add extra libraries to PixiJS to compensate for its lack of built-in functionality, the problem is that the bundle size and codebase complexity will increase, which may make the bundle size advantage that PixiJS has insignificant.

If your game needs to be screen-reader accessible or if you want to create complex interactive graphics for games or other types of digital content, PixiJS is the best option.

For 2D browser games, Phaser is the best choice as it has many useful game functions built in. If the bundle size of your game is critical and you can build a lot of the game functionality yourself, then PixiJS is a better choice.

Another option for a beginner-friendly game framework is Kaboom.js. Here's a tutorial where you can learn how to build Flappy Bird with Kaboom.js.

Create a Discord RPG bot with Python

RitzaCo — Fri, 12 Aug 2022 10:14:00 +0000

In this tutorial, we'll create a text-based RPG that users of a Discord server can play by entering special commands. Users will be able to create characters, fight enemies, and earn experience and gold, which they can use to develop their skills and buy powerful items.

By the end of this tutorial, you will have:

Used discord.py to create an RPG that can be added to any Discord server, and which can be expanded as you see fit.
Used Replit Database to store information about the game world through serialization.
Created a custom Discord message embed.
Hosted your own Discord bot on Replit!

Getting started

Game design

Before we dive into writing code, it's worth taking a moment to think about how our game is going to work and what options we're going to give our players. Our game will be text-based and played on a Discord server. Players will take actions by issuing commands to a Discord bot, and the bot will respond with the results of those actions.

Players will start the game by creating a character, whom they can name. This character will have the following:

Hitpoints to determine how much damage they can take.
Attack and defense skills to determine how they fare in battle.
A level and experience points.
Mana for casting spells.
An inventory for collecting items.
Gold for purchasing items.

Characters will gain experience and gold for fighting and defeating enemies. They will be able to seek out enemies and battle them. In battle mode, they will be able to fight, use an item, or flee if it doesn't look like they're going to win. Battles will continue until one participant runs out of hitpoints, or until the player's character flees.

At the end of a successful battle, characters will gain experience points and gold, based on the strength of the defeated enemy. If a character is defeated in battle, they will die and the player will have to create a new character.

At certain thresholds of experience points, characters will level up. Every time a player levels up their character, they will be able to choose to increase the character's hitpoints, attack, defense, or mana.

While we've included gold, mana, and an inventory in our design, the implementation of these aspects will be left as an exercise for the reader. For this tutorial, we'll focus on implementing battling enemies and leveling up.

To facilitate the above, our game will need two modes:

Adventure mode, in which players can hunt for enemies and level up.
Battle mode, in which players can fight enemies.

We will also need a few commands for players to take game actions:

!create <name>: Create a new character with the name provided.
!status: Display the character's current hitpoints, level, carried items, and other information.
!die: Destroy the current character.
!hunt: (In adventure mode) seek out an enemy to fight.
!fight: (In battle mode) attack an enemy.
!flee: (In battle mode) flee from a battle.
!levelup <stat>: (In adventure mode) advance to the next level if enough XP is available, increasing the provided stat (hitpoints, attack, defense, mana).

Game classes

Before we start on the Discord code, let's create some classes to represent the characters, enemies, modes, and items in our game. In your repl, create a new file named game.py and add the following import code to it:



from replit import db
import enum, random, sys
from copy import deepcopy

We're pulling in the Python library for Replit Database, a persistent key-value store attached to every repl. If you haven't used this before, think of it as a Python dictionary with contents that persist between restarts of your repl. We'll be using it to store the state of our game and its characters as they fight enemies and level up.

Additionally, we're importing the Python built-in libraries enum, random, sys, and deepcopy() from copy. These will provide a number of helpful utilities we'll use while building our game.

First off, we'll use enum.IntEnum to enumerate our game modes. Add the following code below your imports:



# Game modes
class GameMode(enum.IntEnum):
    ADVENTURE = 1
    BATTLE = 2

Whenever we refer to a game mode in our code, we'll be able to write GameMode.ADVENTURE or GameMode.BATTLE, rather than the meaningless numbers 1 or 2, but our code and database will see these game modes as 1 and 2. This saves us from having to remember which game mode is which and will make our code clearer.

Next, we'll create classes for living creatures, such as players' characters and the enemies they fight. As these will all share several properties and behaviors, such as hitpoints and the ability to fight, we'll use inheritance to save ourselves some repetition. Our class hierarchy will look like this (but with a few more enemy types):



       ,-----.             
       |Actor|             
       |-----|             
       {% raw %}`-----'             
         / \               
        /   \              
,---------.  ,-----.       
|Character|  |Enemy|       
|---------|  |-----|       
`---------'  `-----'       
              /    \       
      ,--------.   ,------.
      |GiantRat|   |Dragon|
      |--------|   |------|
      `--------'   `------'
```

Let's start by implementing our parent class, `Actor`. This class will define all of the attributes that characters and enemies have in common and implement a `fight()` method. Add the following code at the bottom of `game.py`:

```python
# Living creatures
class Actor:

    def __init__(self, name, hp, max_hp, attack, defense, xp, gold):
        self.name = name
        self.hp = hp
        self.max_hp = max_hp
        self.attack = attack
        self.defense = defense
        self.xp = xp
        self.gold = gold

    def fight(self, other):
        defense = min(other.defense, 19) # cap defense value
        chance_to_hit = random.randint(0, 20-defense)
        if chance_to_hit: 
            damage = self.attack
        else:
            damage = 0

        other.hp -= damage

        return (self.attack, other.hp <= 0) #(damage, fatal)
```

Our `__init__()` method defines several variables per our game design specification above. Note that we've defined both `hp` and `max_hp`: these should be the same value when we first create a character or enemy class, but will diverge for characters and enemies we read from the database. Once we get into the game logic, we will be recreating instances of these classes from the database constantly.

Also note that `self.xp` will represent something slightly different in characters and enemies: For characters, it will be the cumulative experience points earned, whereas for enemies it will be the amount of XP rewarded to characters when the enemy is defeated. A more complex design might instead enable enemies to gain experience points and level up like player characters.

The `fight()` method takes `other`, an instance of a class that inherits from `Actor`. The attack is simulated by first calculating the chance to hit based on the opponent's `defense` attribute. If `chance_to_hit` is 0, the attack will miss. The likelihood of a miss happening increases in probability as the `defense` value increases. For example, an attack will have a 95% chance of succeeding against an enemy with a `defense` of 1, but only a 50% chance of succeeding against an enemy with `defense` of 19. We use Python's built-in `min()` function to cap the value of `defense` at 19, to avoid creating a completely invulnerable character.

The damage done on a successful hit is determined by the `Actor`'s `attack` attribute. The function returns a tuple of the amount of damage dealt by the attack and whether it was the fatal blow.

Our `Actor` class is complete for now. Let's create a `Character` class that inherits from it and will represent players. Add the following code to the bottom of the `game.py` file:

```python
class Character(Actor):

    level_cap = 10

    def __init__(self, name, hp, max_hp, attack, defense, mana, level, xp, gold, inventory, mode, battling, user_id):
        super().__init__(name, hp, max_hp, attack, defense, xp, gold)
        self.mana = mana
        self.level = level

        self.inventory = inventory 

        self.mode = mode
        self.battling = battling
        self.user_id = user_id
```

Our `Character` class has all the same attributes as `Actor`, plus some additional ones:

* `mana` represents the character's capacity for casting spells.
* `level` is the character's level. This will start at 1 and increase with every 10 XP the player earns.
* `inventory` is a list of items carried by the character.
* `mode` is the game mode we defined an enum for above. Two characters will be in different modes depending on their actions.
* `battling` is a variable we'll use to store the enemy object that the character is currently fighting. This will be `None` outside of battle mode.
* `user_id` is the Discord user ID of the user who created this character.

Also, note the [class variable](https://www.digitalocean.com/community/tutorials/understanding-class-and-instance-variables-in-python-3) `level_cap`: this will be the highest possible value of `level`.

We'll come back to the `Character` class and use it to implement gameplay actions later, but first let's define the enemy classes, starting with `Enemy`.

```python
class Enemy(Actor):

    def __init__(self, name, max_hp, attack, defense, xp, gold):
        super().__init__(name, max_hp, max_hp, attack, defense, xp, gold)
```

For now, this is a straightforward subclass of `Actor` that uses the same value for `hp` and `max_hp` but doesn't define anything extra. We'll specify the actual stats of individual enemy types in the `Enemy` subclasses, of which we'll define ten. Copy-paste the code below at the bottom of `game.py` to implement those classes:

```python
class GiantRat(Enemy):
    min_level = 1
    def __init__(self):
        super().__init__("🐀 Giant Rat", 2, 1, 1, 1, 1) # HP, attack, defense, XP, gold

class GiantSpider(Enemy):
    min_level = 1
    def __init__(self):
        super().__init__("🕷️ Giant Spider", 3, 2, 1, 1, 2) # HP, attack, defense, XP, gold

class Bat(Enemy):
    min_level = 1
    def __init__(self):
        super().__init__("🦇 Bat", 4, 2, 1, 2, 1) # HP, attack, defense, XP, gold

class Crocodile(Enemy):
    min_level = 2
    def __init__(self):
        super().__init__("🐊 Crocodile", 5, 3, 1, 2, 2) # HP, attack, defense, XP, gold

class Wolf(Enemy):
    min_level = 2
    def __init__(self):
        super().__init__("🐺 Wolf", 6, 3, 2, 2, 2) # HP, attack, defense, XP, gold

class Poodle(Enemy):
    min_level = 3
    def __init__(self):
        super().__init__("🐩 Poodle", 7, 4, 1, 3, 3) # HP, attack, defense, XP, gold

class Snake(Enemy):
    min_level = 3
    def __init__(self):
        super().__init__("🐍 Snake", 8, 4, 2, 3, 3) # HP, attack, defense, XP, gold

class Lion(Enemy):
    min_level = 4
    def __init__(self):
        super().__init__("🦁 Lion", 9, 5, 1, 4, 4) # HP, attack, defense, XP, gold

class Dragon(Enemy):
    min_level = 5
    def __init__(self):
        super().__init__("🐉 Dragon", 10, 6, 2, 5, 5) # HP, attack, defense, XP, gold
```

In addition to providing names and hardcoded HP, attack, defense, XP, and gold values, we've implemented `min_level` as a class variable. This specifies the minimum level the player must be to face this enemy. By implementing this, we avoid having low-level players die instantly against too-powerful enemies and ensure that new enemies will show up as the player levels up, creating a sense of progression. Feel free to change any of these enemies, or add your own.

## Saving and loading from the database

We've now defined our player and enemy classes, though they don't do much. But before we implement any actual gameplay, we need a way to ensure that our characters and enemies maintain their state from one moment to the next. Presently, any `Actor` instances we create will disappear as soon as our repl finishes running or is stopped. We need to use our repl's database to ensure that players can keep the characters they create and that changes such as losing and gaining HP and leveling up will persist.

The most important objects in our game are the instances of `Character`. These objects store character stats, inventory, and even game mode and the enemy currently being fought. So as long as we can save and load the state of individual characters from our database, our game world will feel permanent. For now, we don't need to worry about storing anything else.

Return to the definition of `Character` and add the following `save_to_db()` method below the `__init__()` method:

```python
class Character(Actor):

    # ...

    def save_to_db(self):
        character_dict = deepcopy(vars(self))
        if self.battling != None:
            character_dict["battling"] = deepcopy(vars(self.battling))

        db["characters"][self.user_id] = character_dict
```

At the top of `game.py`, we imported `db` from the `replit` Python library – this object provides an interface to our repl's database. The `db` object is designed to be used like a dictionary, so we can create keys and values as we would with any other dictionary. Our database layout will look like this:

```
{
    "characters": {
        "123456789012345678": {
            "name": "Bob the Dwarf"
            "hp": 10,
            ...
        },
        "823486788042375673": {
            "name": "Eric the Human"
            "hp": 8,
            ...
        },
        ...
    }
}
```

The [`vars()` function](https://docs.python.org/3/library/functions.html#vars) is a Python built-in that returns the value of `__dict__` for any class, module, or instance we pass to it. For most instances, this will be a dictionary containing that instance's attributes. In the case of our `Character` object, the dictionary will contain all of the attributes we defined in `__init__`. We use [`deepcopy()`](https://docs.python.org/3/library/copy.html#copy.deepcopy) to make a full copy of this dictionary. 

Any attributes that contain strings, numbers, boolean values, or even lists or dictionaries can be easily and meaningfully stored in our repl's database. Attributes that reference instances of our custom classes cannot be usefully stored, as the referenced instance may not exist the next time the data is loaded. The `deepcopy()` operation alone does not solve this problem. Thus, we need to store the object referenced by `battling` as a dictionary of its attributes using `vars()`, just like we did for the `Character` instance.

However, we have a slight problem: While we can store the attributes of the enemy, this way we're not storing its class. There are a few ways we could resolve this issue – the easiest one is to store the instance's class name as an attribute. Go to your `Enemy` class's `__init__()` method and add the following line:

```python
class Enemy(Actor):

    def __init__(self, name, max_hp, attack, defense, xp, gold):
        super().__init__(name, max_hp, max_hp, attack, defense, xp, gold)
        # NEW LINE BELOW
        self.enemy = self.__class__.__name__
```

This new line will store the name of the class as a string, which we can write to the database.

We've now written all the code we'll need to save player characters to the database. Now we need a way to load them back into the game. Fortunately, we already have most of what we need to do this in our `Character.__init__()` method. A line of code like the following will initialize a new `Character` with details from our database:

```python
Character(**db["characters"]["123456789012345678"])
```

The only problem here is that the value of `battling` will be a dictionary rather than a subclass of `Enemy`. We can fix this by making some changes to `Character.__init__()`. Find the method and replace the line `self.battling = battling` with the new code below:

```python
class Character(Actor):

    level_cap = 10

    def __init__(self, name, hp, max_hp, attack, defense, mana, level, xp, gold, inventory, mode, battling, user_id):
        super().__init__(name, hp, max_hp, attack, defense, xp, gold)
        self.mana = mana
        self.level = level

        self.inventory = inventory 

        self.mode = mode
        # NEW CODE BELOW THIS LINE
        if battling != None:
            enemy_class = str_to_class(battling["enemy"])
            self.battling = enemy_class()
            self.battling.rehydrate(**battling)
        else:
            self.battling = None
        # NEW CODE ABOVE THIS LINE

        self.user_id = user_id
```

This code converts the value of the `enemy` attribute we created above from a string into a class, initializes a copy of that class, and then calls `rehydrate`, unpacking the `battling` dictionary as its arguments. We'll write both the `str_to_class` function and the `Enemy.rehydrate()` method shortly.

The `str_to_class` function will take a `string` and return the `class` with its name.

The `rehydrate` method will set all attributes of the instance to those provided. While we could do this with the `__init__()` method as we did with `Character`, this would force us to specify all our attribute values every time we initialize any subclass of `Enemy`, defeating the point of having subclasses in the first place.

Navigate to the top of `game.py` and create the `str_to_class` function just below your imports, as below:

```python
# Helper functions
def str_to_class(classname):
    return getattr(sys.modules[__name__], classname)
```

This function uses the useful Python built-in [`getattr`](https://docs.python.org/3/library/functions.html#getattr) to retrieve the class corresponding to the string provided as `classname`. Note that this function will only work for the classes we define.

Next, return to your `Enemy` class and create the `rehydrate()` method just below the `__init__()` method.

```python
class Enemy(Actor):

    def __init__(self, name, max_hp, attack, defense, xp, gold):
        super().__init__(name, max_hp, max_hp, attack, defense, xp, gold)
        self.enemy = self.__class__.__name__

    # NEW METHOD
    def rehydrate(self, name, hp, max_hp, attack, defense, xp, gold, enemy):
        self.name = name
        self.hp = hp
        self.max_hp = max_hp
        self.attack = attack
        self.defense = defense
        self.xp = xp
        self.gold = gold
```

Note that we're accepting `enemy` as an argument without using it. This is to prevent errors when unpacking the `battling` dictionary.

We will now be able to save characters to the database by calling `save_to_db()` and load characters from the database by passing a database entry to `Character()`. As our characters store information about the enemies they're fighting, this is all we need for a persistent game world.

## Game actions

Let's implement the player actions from our design specification. We'll start with hunting, the action that enables characters to seek out enemies to fight. Add the following code to the class definition of `Character`:

```python
    def hunt(self):
        # Generate random enemy to fight
        while True:
            enemy_type = random.choice(Enemy.__subclasses__())

            if enemy_type.min_level <= self.level:
                break

        enemy = enemy_type()

        # Enter battle mode
        self.mode = GameMode.BATTLE
        self.battling = enemy

        # Save changes to DB after state change
        self.save_to_db()

        return enemy
```

First, we use [`random.choice()`](https://docs.python.org/3/library/random.html#random.choice) to choose one of the subclasses of `Enemy` at random. This random selection will be repeated until we chose an enemy with a minimum level less than or equal to our player character's level.

Once the enemy is chosen, we initialize an instance of it, switch the game mode, and save a reference to it in `battling`. We then update the player object in the database and return the enemy object.

We will need to call `save_to_db()` at the end of every method that changes the character's state. This includes the `fight()` method defined in `Actor`. Add the following method to the `Character` class to accomplish this:

```python
   def fight(self, enemy):
        outcome = super().fight(enemy)

        # Save changes to DB after state change
        self.save_to_db()

        return outcome
```

This method will call `Actor.fight()`, store its result, update the database, and then return the result.

Next, we'll define a `flee()` method for escaping from a battle the player character is unlikely to win. Add the following method at the bottom of `Character`:

```python
    def flee(self, enemy):
        if random.randint(0,1+self.defense): # flee unscathed
            damage = 0
        else: # take damage
            damage = enemy.attack/2
            self.hp -= damage

        # Exit battle mode
        self.battling = None
        self.mode = GameMode.ADVENTURE

        # Save to DB after state change
        self.save_to_db()

        return (damage, self.hp <= 0) #(damage, killed)
```

To add some uncertainty to the flee action, as well as an additional use for the defense stat, we've implemented a random chance that the player will take a small amount of damage on fleeing. We then empty `battling`, change the game mode, save the state, and return a tuple of the action outcome, similar to the one returned in `Actor.fight()`.

Next, we'll need a method to call after an enemy is defeated, to give the player character their gold and XP. Add the following method definition:

```python
    def defeat(self, enemy):
        if self.level < self.level_cap: # no more XP after hitting level cap
            self.xp += enemy.xp

        self.gold += enemy.gold # loot enemy

        # Exit battle mode
        self.battling = None
        self.mode = GameMode.ADVENTURE

        # Check if ready to level up after earning XP
        ready, _ = self.ready_to_level_up()

        # Save to DB after state change
        self.save_to_db()

        return (enemy.xp, enemy.gold, ready)
```

If the player's level is below the cap, we add the enemy's XP onto their own. We then add the enemy's gold to their coin-purse, exit battle mode, and check if they've gained enough XP to level up (using a method we'll implement later). Finally, we save the character's state to the database and return a tuple of the results of this action.

Let's define `ready_to_level_up()` next:

```python
    def ready_to_level_up(self):
        if self.level == self.level_cap: # zero values if we've ready the level cap
            return (False, 0)

        xp_needed = (self.level)*10
        return (self.xp >= xp_needed, xp_needed-self.xp) #(ready, XP needed)
```

This method merely checks whether the current XP is greater than or equal to ten times the character's level. Characters will need 10 XP to advance to level 2, 20 XP to advance to level 3, etc. The method returns a tuple containing a Boolean that indicates whether the character is ready to level up and the amount of XP still needed. As it does not change the character's state, we do not need a call to `save_to_db`.

Now that we're increasing the player's XP and checking whether they're ready to level up, we need a method to level them up. Add the following method:

```python
    def level_up(self, increase):
        ready, _ = self.ready_to_level_up()
        if not ready:
            return (False, self.level) # (not leveled up, current level)

        self.level += 1 # increase level
        setattr(self, increase, getattr(self, increase)+1) # increase chosen stat

        self.hp = self.max_hp #refill HP

        # Save to DB after state change
        self.save_to_db()

        return (True, self.level) # (leveled up, new level)
```

After ensuring that the player is ready to level up, we increase their level and use Python built-ins [`setattr`](https://docs.python.org/3/library/functions.html#setattr) and [`getattr`](https://docs.python.org/3/library/functions.html#getattr) to increment one of the character's stats. We reset their HP to the max value, save the state, and finally return the outcome of the action (a tuple indicating whether leveling up succeeded and what the character's new level is).

The last method we need is `die()`, which will be called when a character is defeated in battle. We could handle player death in a few different ways, but for the sake of simplicity, we'll just delete the character from the database.

```python
    def die(self, player_id):
        if self.user_id in db["characters"].keys():
            del db["characters"][self.user_id]
```

That's a wrap for our game's logic. Next, we'll integrate with Discord and make our game playable.

## Creating a Discord application

Discord will serve as the display layer for our game, allowing players to issue commands and see the results of those commands.

Open another browser tab and visit the [Discord Developer Portal](http://discordapp.com/developers/applications). Log in with your Discord account, or create one if you haven't already. Keep your repl open – we'll return to it soon.

Once you're logged in, create a new application. Give it a name like "MyRPG".

![Discord create app](https://replit-docs-images.bardia.repl.co/images/tutorials/discord-rpg-bot/discord-create-app.png)

Discord applications can interact with Discord in several different ways, not all of which require bots, so creating one is optional. That said, we'll need one for this project. Let's create a bot.

1. Click on **Bot** in the menu on the left-hand side of the page.
2. Click **Add Bot**.
3. Give your bot a username (such as "RPGBot").
4. Click **Reset Token** and then **Yes, do it!**.
4. Copy the token that appears just under your bot's username.

![Discord create bot](https://replit-docs-images.bardia.repl.co/images/tutorials/discord-rpg-bot/discord-create-bot.png)

The token you just copied is required for the code in our repl to interface with Discord's API. Return to your repl and open the Secrets tab in the left sidebar. Create a new secret with `DISCORD_TOKEN` as its key and the token you copied as its value.


![secret token](https://replit-docs-images.bardia.repl.co/images/tutorials/discord-rpg-bot/secret-token.png)


Once you've done that, return to the Discord developer panel. We need to finish setting up our bot.

You can leave the **Public Bot** option enabled or disable it, depending on whether you'd like other people to be able to find and install your bot on their server. Keep in mind that bots on 100 or more servers have to go through a special verification and approval process.

![Public Bot option](https://replit-docs-images.bardia.repl.co/images/tutorials/discord-rpg-bot/public-bot.png)

Next, we need to configure access to privileged [Gateway Intents](https://discord.com/developers/docs/topics/gateway#gateway-intents). Depending on a bot's functionality, it will require access to different events and sources of data. Events involving users' actions and the content of their messages are considered more sensitive and need to be explicitly enabled.

For this bot to work, we'll need the **Message Content Intent**, which will allow our bot to see the content of users' messages. Toggle it to the on position and save changes when prompted.

![Bot intents](https://replit-docs-images.bardia.repl.co/images/tutorials/discord-rpg-bot/bot-intents.png)

Now that we've created our application and its bot, we need to add it to a server. We'll walk you through creating a test server for this tutorial, but you can also use any server you've created in the past, as long as the other members won't get too annoyed about it becoming a bot testing ground. You can't use a server that you're just a normal user on, as adding bots requires special privileges.

Open [Discord](http://discord.com) in your browser. You should already be logged in. Then click on the **+** icon in the leftmost panel to create a new server. Alternatively, open an existing server you own.

In a separate tab, return to the [Discord Dev Portal](https://discord.com/developers/applications) and open your application. Then follow these steps to add your bot to your server:

1. Click on **OAuth2** in the left sidebar.
2. In the menu that appears under **OAuth2**, select **URL Generator**.
3. Under **Scopes**, mark the checkbox labelled *bot*.
4. Under **Bot Permissions**, mark the checkboxes labelled *Read Messages/View Channels* and *Send Messages*.
    ![Bot permissions](https://replit-docs-images.bardia.repl.co/images/tutorials/discord-rpg-bot/bot-permissions.png)

5. Scroll down and copy the URL under **Generated URL**.
6. Paste the URL in your browser's navigation bar and hit enter.
7. On the page that appears, select your server from the drop-down box and click **Continue**.
8. When prompted about permissions, click **Authorize**, and complete the CAPTCHA.
    ![Bot connect](https://replit-docs-images.bardia.repl.co/images/tutorials/discord-rpg-bot/bot-connect.png)

9. Return to your Discord server. You should see that your bot has just joined.

Now that we've done the preparatory work, it's time to write some code. Return to your repl for the next section.

## Writing the Discord bot code 

We'll be using [discord.py](https://discordpy.readthedocs.io/en/stable/) to interface with Discord's API using Python. Open `main.py` in your repl and add the following code:

```python
import os, discord
from discord.ext import commands

from replit import db
from game import *

DISCORD_TOKEN = os.getenv("DISCORD_TOKEN")

bot = commands.Bot(command_prefix="!")

@bot.event
async def on_ready():
    print(f"{bot.user} has connected to Discord!")

bot.run(DISCORD_TOKEN)
```

First, we import the Python libraries we'll need, including discord.py and its [commands extension](https://discordpy.readthedocs.io/en/stable/ext/commands/commands.html), as well as our database and the contents of `game.py`.

We then retrieve the value of the `DISCORD_TOKEN` environment variable, which we set in our repl's Secrets tab above. Following that, we instantiate a [`Bot` object](https://discordpy.readthedocs.io/en/stable/ext/commands/api.html#discord.ext.commands.Bot). We'll use this object to listen for Discord events and respond to them. For the most part, we'll be responding to *commands*: messages from users which start with `!` (the `command_prefix` we specified when creating our `Bot` object).

However, the first event we're interested in is not a command. The [`on_ready()`](https://discordpy.readthedocs.io/en/stable/api.html#discord.on_ready) event will trigger when our bot logs onto Discord (the `@bot.event` [decorator](https://realpython.com/primer-on-python-decorators/) ensures this). All this event will do is print a message to our repl's console, telling us that the bot has connected.

Note that we've prepended `async` to the function definition – this makes our `on_ready()` function into a [coroutine](https://docs.python.org/3/library/asyncio-task.html). Coroutines are largely similar to functions, but may not execute immediately, and must be invoked with the `await` keyword. Using coroutines makes our program [asynchronous](https://realpython.com/async-io-python/#the-10000-foot-view-of-async-io), which means it can continue executing code while waiting for the results of a long-running function, usually one that depends on input or output. If you've used JavaScript before, you'll recognize this style of programming.

The final line in our file starts the bot, providing `DISCORD_TOKEN` to authenticate it. Run your repl now to see it in action. Once it's started, return to your Discord server. You should see that your bot user is now online.

![Online bot](https://replit-docs-images.bardia.repl.co/images/tutorials/discord-rpg-bot/online-bot.png)

## Handling user commands

Now we can start writing the handlers for our game's actions, such as `!create`, `!hunt`, and `!fight`.

The discord.py commands extension allows us to define command handlers using the `@bot.command` decorator. Without this, we'd have to manually parse the content of all user messages to determine whether a command has been issued, as was necessary for our [role assignment bot tutorial](https://docs.replit.com/tutorials/discord-role-bot).

### Character creation

First, we'll implement our character creation command, `!create`. Add the following code to `main.py` below the definition of `on_ready()`:

```python
# Commands
@bot.command(name="create", help="Create a character.")
async def create(ctx, name=None):
    user_id = ctx.message.author.id

    # if no name is specified, use the creator's nickname
    if not name:
        name = ctx.message.author.name

```

The `@bot.command` decorator will ensure that our function is invoked when a user types a message starting with `!create`. We also use it to define some help text – the commands extension provides a default `!help` command, and each command we define can have two types of explanatory text:

* `brief`: A short description of the command that will show alongside other defined commands when the user types `!help`.
* `help`: A longer description of the command that will show when the user types `!help name_of_command`. 

In the absence of `brief`, the `help` text will be used in both cases, though it may be truncated for the output of `!help`.

Our `create` function takes two parameters:

* `ctx`: This is the *invocation context*, a special object containing information such as the user who called the command, the server it was called in, and the files attached to the calling message if any. All commands must take this parameter.
* `name`: This will be the name for the character we're creating and is an optional parameter.

The function body retrieves the Discord user ID of the user who issued the `!create` command. It then checks whether a `name` parameter was provided. If not, it sets `name` to the name of the user.

Next, we'll create an instance of `Character` with some starter stats and save it to our repl's database. Add the following code to the body of `create`:

```python
    # create characters dictionary if it does not exist
    if "characters" not in db.keys():
        db["characters"] = {}

    # only create a new character if the user does not already have one
    if user_id not in db["characters"] or not db["characters"][user_id]:
        character = Character(**{
            "name": name,
            "hp": 16,
            "max_hp": 16,
            "attack": 2,
            "defense": 1,
            "mana": 0,
            "level": 1,
            "xp": 0,
            "gold": 0,
            "inventory": [],
            "mode": GameMode.ADVENTURE,
            "battling": None,
            "user_id": user_id
        })
        character.save_to_db()
        await ctx.message.reply(f"New level 1 character created: {name}. Enter `!status` to see your stats.")
    else:
        await ctx.message.reply("You have already created your character.")
```

After creating and saving a new character, or failing to do so, this code sends a [reply](https://support.discord.com/hc/en-us/articles/360057382374-Replies-FAQ) to the message that invoked it. As our game logic primarily resides in the `game.py` file, constructing these commands will largely be a matter of constructing and sending replies informing the player of what's happened in the game world. 

### Character status

Next, we'll implement the `!status` command, which players will use to view their character's current statistics, inventory, and game mode. To convey this information compactly and attractively, we'll use an [embed](https://python.plainenglish.io/send-an-embed-with-a-discord-bot-in-python-61d34c711046) rather than a plain Discord message.

Embeds are usually used to provide link previews, but can also be constructed from scratch, providing a powerful tool for bots to display richly formatted information of any kind. This is what our embed will look like:

![Status embed](https://replit-docs-images.bardia.repl.co/images/tutorials/discord-rpg-bot/status-embed.png)

Add the following function below the definition `create()`:

```python
@bot.command(name="status", help="Get information about your character.")
async def status(ctx):
    character = load_character(ctx.message.author.id)

    embed = status_embed(ctx, character)
    await ctx.message.reply(embed=embed)
```

This function retrieves the player's character from the database, passes it and the current context to a function that will construct and return an embed, and then replies with the embed. We'll implement the two methods we've used just above the definition of `on_ready()`. Go there now.

First, `load_character()`, which reads from the database and creates an instance of `Character` using the results:

```python
# Helper functions
def load_character(user_id):
    return Character(**db["characters"][str(user_id)])
```

Second, `status_embed()`:

```python
MODE_COLOR = {
    GameMode.BATTLE: 0xDC143C,
    GameMode.ADVENTURE: 0x005EB8,
}
def status_embed(ctx, character):

    # Current mode
    if character.mode == GameMode.BATTLE:
        mode_text = f"Currently battling a {character.battling.name}."
    elif character.mode == GameMode.ADVENTURE:
        mode_text = "Currently adventuring."

    # Create embed with description as current mode
    embed = discord.Embed(title=f"{character.name} status", description=mode_text, color=MODE_COLOR[character.mode])
    embed.set_author(name=ctx.author.display_name, icon_url=ctx.author.avatar_url)
```

Just above the function definition, we've created a dictionary that maps game modes to colors. We'll use this to change the color of the vertical bar on the left side of the embed.

In the function itself, we first check the game mode. This will determine the embed's description text, a paragraph that appears just below the embed's title. Once that's done, we create the embed with [`discord.Embed`](https://discordpy.readthedocs.io/en/stable/api.html#discord.Embed), setting the title, description, and color. We then use [`set_author()`](https://discordpy.readthedocs.io/en/stable/api.html#discord.Embed.set_author) to include the calling user's name and profile picture at the top of the embed.

Next, we will construct the embed's [`fields`](https://discordpy.readthedocs.io/en/stable/api.html#discord.Embed.fields). You can think of these as individual text boxes, which will be displayed below the description. We'll start with a stats field:

```python
    # Stats field
    _, xp_needed = character.ready_to_level_up()

    embed.add_field(name="Stats", value=f"""
**HP:**    {character.hp}/{character.max_hp}
**ATTACK:**   {character.attack}
**DEFENSE:**   {character.defense}
**MANA:**  {character.mana}
**LEVEL:** {character.level}
**XP:**    {character.xp}/{character.xp+xp_needed}
    """, inline=True)
```

We've used [`add_field()`](https://discordpy.readthedocs.io/en/stable/api.html#discord.Embed.add_field) to create a field with the title "Stats" that contains a listing of all the player's important stats. Note the call to `character.ready_to_level_up()`, so that we can show the player how much XP they need to advance to the next level. We've also set `inline=True`, which allows us to display fields as columns.

Our next column will show the player's inventory:

```python
    # Inventory field
    inventory_text = f"Gold: {character.gold}\n"
    if character.inventory:
        inventory_text += "\n".join(character.inventory)

    embed.add_field(name="Inventory", value=inventory_text, inline=True)
```

There's currently no logic in our game to put items into characters' inventories, but you should see characters' gold increase as they defeat enemies.

Finally, we'll return the embed.

```python
    return embed 
```

Run your repl now, and then switch tabs to your Discord server. Create a character with `!create` and view its status with `!status`.

![Create character](https://replit-docs-images.bardia.repl.co/images/tutorials/discord-rpg-bot/create-character.png)

### Battles

Next, let's implement our battle commands, starting with `!hunt`. Add the following function definition below the body of `status()`:

```python
@bot.command(name="hunt", help="Look for an enemy to fight.")
async def hunt(ctx):
    character = load_character(ctx.message.author.id)

    if character.mode != GameMode.ADVENTURE:
        await ctx.message.reply("Can only call this command outside of battle!")
        return

    enemy = character.hunt()

    # Send reply
    await ctx.message.reply(f"You encounter a {enemy.name}. Do you `!fight` or `!flee`?")
```

This function is fairly simple: We load the character, ensure they're not currently in a battle, call `hunt()` to generate a random enemy, and reply to the player with a message about what they're fighting and which commands they can use.

Next, we'll implement `!fight`:

```python
@bot.command(name="fight", help="Fight the current enemy.")
async def fight(ctx):
    character = load_character(ctx.message.author.id)

    if character.mode != GameMode.BATTLE:
        await ctx.message.reply("Can only call this command in battle!")
        return

    # Simulate battle
    enemy = character.battling

    # Character attacks
    damage, killed = character.fight(enemy)
    if damage:
        await ctx.message.reply(f"{character.name} attacks {enemy.name}, dealing {damage} damage!")
    else:
        await ctx.message.reply(f"{character.name} swings at {enemy.name}, but misses!")
```

Here we load the character, ensure they're currently in battle mode, and then have them fight the enemy, returning a message about the damage inflicted. We also account for the small chance that they will inflict no damage.

Next, we need to check if the enemy was killed by the attack. Add the following code to the bottom of the function:

```python
    # End battle in victory if enemy killed
    if killed:
        xp, gold, ready_to_level_up = character.defeat(enemy)

        await ctx.message.reply(f"{character.name} vanquished the {enemy.name}, earning {xp} XP and {gold} GOLD. HP: {character.hp}/{character.max_hp}.")

        if ready_to_level_up:
            await ctx.message.reply(f"{character.name} has earned enough XP to advance to level {character.level+1}. Enter `!levelup` with the stat (HP, ATTACK, DEFENSE) you would like to increase. e.g. `!levelup hp` or `!levelup attack`.")

        return
```

Here we call `character.defeat()` to handle the enemy's death and return appropriate replies. Again, we've already written all the game logic, so all this code needs to do is display it to the player. Once we've sent the reply, we return from the function.

After the player character attacks, we need to have the enemy fight back. Add the following code below the `if killed` block:

```python
    # Enemy attacks
    damage, killed = enemy.fight(character)
    if damage:
        await ctx.message.reply(f"{enemy.name} attacks {character.name}, dealing {damage} damage!")
    else:
        await ctx.message.reply(f"{enemy.name} tries to attack {character.name}, but misses!")

    character.save_to_db() #enemy.fight() does not save automatically
```

This is almost identical to the player's attack code, but with `enemy.fight(character)` instead of `character.fight(enemy)`. But because `enemy.fight()` does not save to the database after changing the game state, we must do this manually.

Next, we need some code to check whether the player character was killed in the attack. Add the following lines to your function:

```python
    # End battle in death if character killed
    if killed:
        character.die()

        await ctx.message.reply(f"{character.name} was defeated by a {enemy.name} and is no more. Rest in peace, brave adventurer.")
        return
```

Here we delete the character from the database, send a message of condolences, and return from the function.

The last case we need to handle is the most common one, where neither the player nor their enemy has died. We'll deal with this by sending a final message to close out this round of fighting.

```python
    # No deaths, battle continues
    await ctx.message.reply(f"The battle rages on! Do you `!fight` or `!flee`?")
```

That's it for `!fight` – now we need `!flee`! Add the following function below the one you just finished:

```python
@bot.command(name="flee", help="Flee the current enemy.")
async def flee(ctx):
    character = load_character(ctx.message.author.id)

    if character.mode != GameMode.BATTLE:
        await ctx.message.reply("Can only call this command in battle!")
        return

    enemy = character.battling
    damage, killed = character.flee(enemy)

    if killed:
        character.die()
        await ctx.message.reply(f"{character.name} was killed fleeing the {enemy.name}, and is no more. Rest in peace, brave adventurer.")
    elif damage:
        await ctx.message.reply(f"{character.name} flees the {enemy.name}, taking {damage} damage. HP: {character.hp}/{character.max_hp}")
    else:
        await ctx.message.reply(f"{character.name} flees the {enemy.name} with their life but not their dignity intact. HP: {character.hp}/{character.max_hp}")
```

Once again, this function loads the character, checks that the game mode is appropriate for the invoked command, and then invokes the appropriate method in `Character`. We finish off the function by providing for three possible outcomes of an attempt to flee: the character dies, the character flees taking damage, and the character flees unscathed.

Rerun your repl and try hunting, fighting, and fleeing.

![Hunt and fight](https://replit-docs-images.bardia.repl.co/images/tutorials/discord-rpg-bot/hunt-and-fight.png)

### Leveling up

Next, we need to implement `!levelup`. Add the following code below the definition of `!flee`:

```python
@bot.command(name="levelup", help="Advance to the next level. Specify a stat to increase (HP, ATTACK, DEFENSE).")
async def levelup(ctx, increase):
    character = load_character(ctx.message.author.id)

    if character.mode != GameMode.ADVENTURE:
        await ctx.message.reply("Can only call this command outside of battle!")
        return

    ready, xp_needed = character.ready_to_level_up()
    if not ready:
        await ctx.message.reply(f"You need another {xp_needed} to advance to level {character.level+1}")
        return

    if not increase:
        await ctx.message.reply("Please specify a stat to increase (HP, ATTACK, DEFENSE)")
        return
```

This function takes `increase`, which will be a string containing the stat to increase. After our standard character load and mode check, we do some error handling. First, we reject the command if the character does not have enough XP to level up, and then we reject the command if the player has not specified a stat to increase.

Next, we need to parse the value of `increase`. Add the following code to your function:

```python
    increase = increase.lower()
    if increase == "hp" or increase == "hitpoints" or increase == "max_hp" or increase == "maxhp":
        increase = "max_hp"
    elif increase == "attack" or increase == "att":
        increase = "attack"
    elif increase == "defense" or increase == "def" or increase == "defence":
        increase = "defense"
```

We're allowing players to increase their characters' HP, attack, or defense stats only. To make our game as user-friendly as possible, we accept a few different words for each of those stats.

Finally, we call the character's `level_up()` method and report on its results:

```python
    success, new_level = character.level_up(increase)
    if success:
        await ctx.message.reply(f"{character.name} advanced to level {new_level}, gaining 1 {increase.upper().replace('_', ' ')}.")
    else:
        await ctx.message.reply(f"{character.name} failed to level up.")
```

Rerun your repl and test this out. If you'd prefer to avoid grinding, edit your character creation code temporarily to increase the initial amount of XP.

![Level up](https://replit-docs-images.bardia.repl.co/images/tutorials/discord-rpg-bot/levelup.png)

### Character death

There's one more command in our design specification that we have not yet implemented: `!die`. Players will use this command if they want to start the game over with a new character. Add the following code to define it:

```python
@bot.command(name="die", help="Destroy current character.")
async def die(ctx):
    character = load_character(ctx.message.author.id)

    character.die()

    await ctx.message.reply(f"Character {character.name} is no more. Create a new one with `!create`.")
```

### Character reset

Before we finish up, we're going to implement one last, special command: `!reset`. This command will delete a player's character and then immediately create a new character. Unlike the commands above, this will be a testing command, for use by the developer rather than players. Add the following code below the definition of `die()`:

```python
@bot.command(name="reset", help="[DEV] Destroy and recreate current character.")
async def reset(ctx):
    user_id = str(ctx.message.author.id)

    if user_id in db["characters"].keys():
        del db["characters"][user_id]

    await ctx.message.reply(f"Character deleted.")
    await create(ctx)
```

Unlike in `die()`, we're deleting from the database directly rather than using `character.die()` method. This is useful because further development of the game might cause errors in `Character.__init__()`, rendering the `die()` method temporarily unusable.

## Where next?

We've created a text-based RPG that can be played on a Discord server, but our game is pretty barebones. We could expand it in a few different ways:

* Implement a magic system using the `mana` attribute.
* Implement an economy in which characters can buy and sell items, such as health potions.
* Flesh out the battle system, with multiple attack types, multiple enemies per battle, and the ability to use items that weaken enemies or temporarily strengthen characters.
* Create a game world with different areas the player can travel to, containing different enemies.
* Implement NPCs the player can talk to and receive quests from.
* Enable player versus player combat.

Discord bot code can be hosted on Replit permanently, but you'll need to use an [Always-on](https://docs.replit.com/hosting/enabling-always-on) repl to keep it running 24/7.

You can find our repl below:
https://replit.com/@ritza/DiscordRPG

Make Snake with vanilla JavaScript

RitzaCo — Wed, 13 Jul 2022 11:02:00 +0000

Snake is a simple game that is great for learning the basics of game development. It can be basic, like the classic Nokia cellphone Snake game, or it can be more complex with added features such as obstacles or making it a two-player game.

In this tutorial, we'll implement a simple version of Snake, using HTML, CSS, and JavaScript.

Getting started

We'll use the Replit web IDE to create our Snake game. This means that you can do this tutorial in the browser, and it will be easy to share your game online. If you don't already have a Replit account, create one now.

For the Snake game, we'll need to:

Create a grid with cells - the game grid where the snake and food will be.
Move the snake from cell to cell.
Control the snake's direction.
Randomly place food items.
Detect when the snake's head touches the food.
Detect when the snake hits the wall of the game grid.
Detect when the snake hits itself.
Keep track of the score - how many food items are eaten.

Let's get started and create a new project in Replit.

Creating a new project in Replit

Head over to Replit and create a new repl. Choose HTML, CSS, JS as your project type.

Setting up the folder structure

Our main JavaScript module will be the script.js file. We'll have a utility module, utils.js for some utility functions. A utility function is a generic function that performs a task that we could reuse in another project. We'll create two utility functions: A wait function that pauses an async function for a defined amount of time and a function to get a random element from an array.

Create a utils.js file so that you have the following files in your project:

|__ index.html
|__ style.css
|__ script.js
|__ utils.js

Adding the HTML

Let's add the HTML needed for the Snake game. Replace the code in your index.html file with the following code:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link rel="stylesheet" href="style.css" />
    <script src="script.js" type="module" defer></script>
    <title>Snake - vanilla JavaScript</title>
  </head>
  <body>
    <button class="start-btn" data-content="Start">Start</button>
    <div class="score">Score: <span>0</span></div>
    <div class="grid"></div>
    <div class="keys-container">
      <button id="ArrowUp">
        <svg width="30" height="30" viewBox="0 0 10 10">
          <g transform="rotate(0, 5, 5)">
            <path d="M5,4 L7,6 L3,6 L5,4" />
          </g>
        </svg>
      </button>
      <button id="ArrowLeft">
        <svg width="30" height="30" viewBox="0 0 10 10">
          <g transform="rotate(-90, 5, 5)">
            <path d="M5,4 L7,6 L3,6 L5,4" />
          </g>
        </svg>
      </button>
      <button id="ArrowDown">
        <svg width="30" height="30" viewBox="0 0 10 10">
          <g transform="rotate(180, 5, 5)">
            <path d="M5,4 L7,6 L3,6 L5,4" />
          </g>
        </svg>
      </button>
      <button id="ArrowRight">
        <svg width="30" height="30" viewBox="0 0 10 10">
          <g transform="rotate(90, 5, 5)">
            <path d="M5,4 L7,6 L3,6 L5,4" />
          </g>
        </svg>
      </button>
    </div>
  </body>
</html>

The type=module attribute on the <script> tag for the script.js file allows us to use module features in our script. The <div> with a class of grid is the game grid. We'll create the cells of the game grid using JavaScript. The <div> with an id of keys contains the up, down, left, and right buttons that we'll use to change the snake's direction on a mobile device. The icons for the keys are created using SVGs.

Adding the CSS

Now let's add some basic styling. Replace the code in your style.css file with the following code:

:root {
  --color-button: #f78400;
  --color-button-after: #f5f5f5;
  --color-button: #424246;
  --color-border: #373737;
}
* {
  margin: 0;
}
html {
  font-family: 'Trebuchet MS', 'Lucida Sans Unicode', 'Lucida Grande',
    'Lucida Sans', Arial, sans-serif;
}
body {
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  height: 100vh;
}
button {
  cursor: pointer;
}
.grid {
  display: flex;
  flex-wrap: wrap;
  border: 2px solid var(--color-border);
  min-height: 200px;
  min-width: 200px;
}
.start-btn {
  position: relative;
  font-size: 1.15rem;
  font-weight: bold;
  background: var(--color-button);
  padding: 0.6rem 1rem;
  margin: 1rem 0;
  border: 0;
}
.start-btn::after {
  position: absolute;
  content: attr(data-content);
  width: 100%;
  height: 100%;
  top: 0;
  left: 0;
  box-shadow: inset 0 0 2px var(--color-border);
  background-color: var(--color-button-after);
  display: flex;
  align-items: center;
  justify-content: center;
  transform: translate(-0.2rem, -0.2rem);
  transition: transform 0.3s cubic-bezier(0.34, 1.56, 0.64, 1);
}
.start-btn:hover::after,
.start-btn:focus::after {
  transform: translate(0);
}
.grid div {
  transition: transform 0.4s ease;
}
.food-item {
  transform: scale(1.15);
}
.keys-container {
  display: grid;
  grid-template-columns: 50px 50px 50px;
  grid-template-rows: auto;
  grid-template-areas:
    '.    up   .'
    'left down right';
  grid-gap: 10px;
  padding: 1rem;
}
.keys-container button {
  background-color: var(--color-button-after);
  border: none;
  padding: 0.5rem;
  box-shadow: 3px 3px 3px rgba(0, 0, 0, 0.3);
  transition: all 0.3s ease;
}
.keys-container button:focus {
  box-shadow: 1px 1px 1px rgba(0, 0, 0, 0.3);
}
#ArrowUp {
  grid-area: up;
}
#ArrowDown {
  grid-area: down;
}
#ArrowLeft {
  grid-area: left;
}
#ArrowRight {
  grid-area: right;
}
.shake {
  animation: shake 0.5s linear 1;
}
@keyframes shake {
  10%,
  90% {
    transform: translate3d(-1px, 0, 0);
  }
  20%,
  80% {
    transform: translate3d(2px, 0, 0);
  }
  30%,
  50%,
  70% {
    transform: translate3d(-4px, 0, 0);
  }
  40%,
  60% {
    transform: translate3d(4px, 0, 0);
  }
}

We use CSS variables to store the colors that we'll use. The body selector uses Flexbox to center the snake game grid on the screen. The start button, which has a class of start-btn, is styled using the ::after pseudo-element. This is done to give the button a layered effect. The ::after pseudo-element is on top of the button, the text is set using the content CSS property. We use a data attribute to label the button. The data attribute data-content was added to the start button in the index.html file. The shake keyframe animation will be used to shake the game grid when the snake hits the walls or itself.

Setting up the JavaScript structure

Replace the code in your script.js file with the following code:

import { randomElementFromArray, wait } from './utils.js';
const foodItemsArray = [
  '🐁',
  '🍇',
  '🍉',
  '🍈',
  '🍓',
  '🍍',
  '🍌',
  '🥝',
  '🍏',
  '🍎',
  '🍔',
  '🍅',
  '🥚',
];

We import the utility functions that we'll soon create. The foodItemsArray variable contains the food items that will be randomly selected and added to the game grid. You can change the food item emojis if you want to.

Adding utility functions

Add the following lines to the utils.js file:

export function wait(ms = 0) {
  return new Promise(resolve => setTimeout(resolve, ms));
}
export function randomElementFromArray(arr) {
  const element = arr[Math.floor(Math.random() * arr.length)];
  return element;
}

The wait function takes in a time, in milliseconds, as an argument. It returns a promise that resolves after the time passed in has elapsed. We'll use it to pause an async function that will be used in the game. The randomElementFromArray function takes in an array as an argument and returns a randomly selected element from the array. We'll use it to randomly select a food item from the foodItemsArray variable.

Now try running the code, by pushing the Run button at the top of the Replit window. You should see the start and arrow buttons:

Building the game logic

Before we start coding the game logic, let's look at an overview of how we'll design the game.

Game overview

There are four main functions we'll use to make the game:

startGame
gameLoop
createFood
moveSnake

We'll run the startGame function when the user clicks start button. In this function, the game grid cells are cleared, the snake and a randomly positioned food item are added to the game grid, and the gameLoop function is run. We run gameLoop every x milliseconds by using setInterval. The snake moves one cell in each game loop.

In the gameLoop function, we check for collisions with the wall of the game grid or the snake itself. We also check if the snake head is in the same cell as a food item. If it is, we remove the food item and create a new randomly positioned food item using the createFood function. The snake length is increased by adding a new tail index to the currentSnake array. We also increase the score.

The snake's body, stored in the currentSnake variable, is represented as an array indicating the cell indexes of the snake. The first element in the array is the snake's head, and the last element in the array is the snake's tail. The game grid cells containing the snake are given a class of snake so that we can detect collisions. We use the cell index positions to style the snake: giving the snake cells a background color and giving the snake head two eyes.

The game grid cell containing the food item is given a class of food-item so that we can detect when the snake collides with this (and eats the food). The cell index of the food item is stored so that we can find the food item cell and place the food item emoji in it. When the game grid is cleared at the start of the game, these added classes are removed from each cell and the cell's inner text content is cleared.

The user can move the snake using the keyboard arrow keys or by clicking the arrow keys on the screen. We listen for the "keydown", "mousedown" or "touchstart" events on the arrow keys and use the moveSnake function to change the direction of the snake. These events change the direction variable value. This variable determines which direction the snake moves. In each game loop, the direction value will be added to the cell index position of the snake's head to give the snake a new head position. The snake's tail will be removed. The direction value indicates the change in index position required for the snake's head to move one cell in the current direction, The direction values are as follows:

right: +1
left: -1
up: -10
down: +10

Now let's create the game.

Creating the game grid

Add the following lines to the script.js file:

// game display elements
const grid = document.querySelector('.grid');
const scoreDisplay = document.querySelector('span');
const startBtn = document.querySelector('.start-btn');
const keyBtns = document.querySelectorAll('.keys-container button');
// game variables
const width = 10;
const numCells = width * width;
grid.style.width = `${width * 10 * 2}px`;
grid.style.height = `${width * 10 * 2}px`;
// create grid cells
for (let i = 0; i < width * width; i++) {
  const cell = document.createElement('div');
  cell.style.width = `${width * 2}px`;
  cell.style.height = `${width * 2}px`;
  grid.appendChild(cell);
}
const cells = document.querySelectorAll('.grid div');

We first get the game display HTML elements from the DOM. We'll only use the grid element now. We then create some of the game variables that we'll need. We set the width to 10 cells and set the game grid's width and height based on the width variable. The square grid is 200 px wide.

We then create the grid cells using a for loop. The number of cells is equal to the width squared. We create each cell using the createElement method. Each square cell is 20 px wide. We then append each cell to the grid. The grid is a flex container and the cells, which are flex items, wrap after each row, which is 10 cells long. We then select the cells using the querySelectorAll method for later use.

Run your code again and you should now be able to see our game grid as a square below the "Start" button.

Adding the snake

Add the following game variables in the // game variables section in the script.js file:

let currentSnake = [2, 1, 0];
let snakeColor = Math.floor(Math.random() * 360);
let snakeColorIncrement = 10;

Now add the following function and event listener to the bottom of the script.js file:

function startGame() {
  currentSnake = [2, 1, 0];
  currentSnake.forEach(i => {
    snakeColor += snakeColorIncrement % 360;
    cells[i].style.background = `hsl(${snakeColor}, 100%, 50%)`;
    cells[i].classList.add('snake');
  });
}
startBtn.addEventListener('click', startGame);

We define the snake's position on the game grid as an array called currentSnake. This indicates the index position of the snake's head [2], body [1] and tail [0] in the game grid. All of the middle elements are the snake's body. At the start of the game, the snake only has one body segment. We also style the snake's body segments using hsla()functional notation. This is done to give our snake a "rainbow" color that changes as it moves. We create a random color value for the hue called snakeColor. This has a value between 0 degrees to 360 degrees. It represents an angle of the color circle: Red = 0 degrees = 360 degrees, green = 120 degrees, blue = 240 degrees, etc.

We loop through the snake segments and give each cell that contains the snake a color. The color changes for each segment as the snakeColor increases in each loop. We also add the class of snake to the game grid cells containing the snake.

Now run the code again and then press the "Start" button in the game UI to see the snake on the game grid:

Each time you press the "Start" button, the snake's color will change. Inspect the snake cells in your browser dev tools. You will see the added snake class and the added background color.

Moving the snake

Let's get the snake moving by adding the gameLoop function. Add the following game variables in the // game variables section in the script.js file:

let direction = 1;
let intervalTime = 200; // determines speed - frequency of game loop calls
let interval = 0;

We set the initial direction to one. In each game loop, the snake's index position in the game grid will increase by one, so the snake will move to the right. The game loop will run five times per second as the interval time is set to 200 ms. The interval variable will be the returned intervalID from the setInterval function that we'll use to run the game loop continuously. The interval variable will be used to cancel the interval so that the game loop is stopped when there is a collision.

Add the following code inside the startGame function, at the top:

  currentSnake.forEach(i => {
    cells[i].style.background = 'none';
    cells[i].classList.remove('snake');
    cells[i].innerText = '';
  });
  clearInterval(interval);
  direction = 1;

At the start of a game, we remove the snake from the game grid cells. We clear the interval to remove any previous interval and set the direction to it's initial value.

Now add the gameLoop function below the startGame function:

function gameLoop() {
  cells[currentSnake[0]].innerText = '';
  const tail = currentSnake.pop();
  cells[tail].classList.remove('snake');
  cells[tail].style.background = 'none';
  currentSnake.unshift(currentSnake[0] + direction); // gives direction to the head
  cells[currentSnake[0]].classList.add('snake');
  cells[currentSnake[0]].innerText = '👀';
  snakeColor += snakeColorIncrement % 360;
  cells[currentSnake[0]].style.background = `hsl(${snakeColor}, 100%, 50%)`;
}

We first clear the innerText of the current snake head to remove the emoji eyes from the current snake head. We then remove the tail and add a new head. To get the index of the new head position in the game grid, we add a new head that has an index of the current snake head plus the current direction. We then style the new head by giving it emoji eyes and a background color.

We also need to call the game loop at the start of the game. Add the following to the startGame function, at the bottom:

interval = setInterval(gameLoop, intervalTime);

Now press the start button to see the snake move along the game grid:

The snake moves from index 0 to 99, incrementing its position by one in each game loop.

Controlling the snake

We'll add a "keydown" event listener and an event handler function to control the snake movement with our keyboard arrow keys. Add the following code below the gameLoop function:

function moveSnake(moveDirection) {
  if (moveDirection === 'ArrowRight') {
    direction = 1;
  }
  if (moveDirection === 'ArrowLeft') {
    direction = -1;
  }
  if (moveDirection === 'ArrowUp') {
    direction = -width;
  }
  if (moveDirection === 'ArrowDown') {
    direction = width;
  }
}
function handleKeyMove(e) {
  if (!['ArrowRight', 'ArrowLeft', 'ArrowUp', 'ArrowDown'].includes(e.key))
    return;
  moveSnake(e.key);
}
document.addEventListener('keydown', handleKeyMove);

We added a "keydown" event listener that is handled by the handleKeyMove function. The handleKeyMove function calls the moveSnake function if one of the arrow keys is pressed down.

The moveSnake function changes the snake's direction, depending on which arrow key was pressed.

You will now be able to change the snake's direction using the arrow keys on your keyboard. However, the snake will be able to move through the walls and move through self. You will also get an error in your console if you go outside of the bounds of the grid by hitting the top or bottom wall. We'll fix this by detecting collisions.

Detecting collisions with the walls and itself

In the gameLoop function, add the following code below the cells[currentSnake[0]].innerText = ''; line:

if (
    (currentSnake[0] + width >= width * width && direction === width) || // hits bottom wall
    (currentSnake[0] % width === width - 1 && direction === 1) || // hits right wall
    (currentSnake[0] % width === 0 && direction === -1) || // hits left wall
    (currentSnake[0] - width < 0 && direction === -width) || // hits the top wall
    cells[currentSnake[0] + direction].classList.contains('snake') // hits itself
  ) {
    grid.classList.add('shake');
    clearInterval(interval);
    return;
  }

This if statement checks if the current snake index is outside the bounds of the game grid. It also checks if the snake hit itself by checking if the next cell that the snake head will move to has the snake class. If there is a collision, the game loop is stopped by clearing the interval and a shake animation is added by adding the shake class to the game grid. This will make the game grid shake when there is a collision. This uses the shake keyframe animation that defined earlier in our style.css file.

For the shake animation to work each time we restart a game, we need to remove the shake class from the game grid at the start of each game. Do this by adding the following line inside of the startGame() function, at the top:

grid.classList.remove('shake');

Now, if your snake hits the wall or itself, it will stop the game loop and the game grid will shake. There are two bugs with the snake direction changes. If you are moving in one direction, then press the arrow key to move in the opposite direction, the snake will hit itself. Also, if your snake is going in one direction and then you make two quick 90-degree turns so that the snake moves in the opposite direction, the snake will hit itself. Let's change the moveSnake function to fix these issues. Replace your moveSnake function with the following:

function moveSnake(moveDirection) {
  let directionVal;
  if (moveDirection === 'ArrowRight' && direction !== -1) {
    directionVal = 1;
    if (currentSnake[0] + directionVal === currentSnake[1]) return;
    direction = directionVal;
  }
  if (moveDirection === 'ArrowLeft' && direction !== 1) {
    directionVal = -1;
    if (currentSnake[0] + directionVal === currentSnake[1]) return;
    direction = directionVal;
  }
  if (moveDirection === 'ArrowUp' && direction !== width) {
    directionVal = -width;
    if (currentSnake[0] + directionVal === currentSnake[1]) return;
    direction = directionVal;
  }
  if (moveDirection === 'ArrowDown' && direction !== -width) {
    directionVal = width;
    if (currentSnake[0] + directionVal === currentSnake[1]) return;
    direction = directionVal;
  }
}

For each direction change, we now check that the direction change is not the opposite of the current direction. We also check that the direction change does not cause the snake's head to hit the first segment of its body.

Adding and eating food

Let's add food items to the game grid. When the snake eats a food item, the score will be increased by one and a new food item will be created. Add the following game variables in the // game variables section:

let foodItemIndex = 0; // first cell
let score = 0;

The foodItemIndex is the cell index in the game grid that the food item will be added to. We'll randomly position it.

Now let's define the createFood function that we'll use to randomly add food items to our game grid. Add the following createFood function above the startGame function:

async function createFood() {
  foodItemIndex = Math.floor(Math.random() * numCells);
  if (currentSnake.includes(foodItemIndex)) {
    await wait(100);
    createFood();
  } else {
    cells[foodItemIndex].classList.add('food-item');
    cells[foodItemIndex].innerText = randomElementFromArray(foodItemsArray);
  }
}

In this recursive async function, we create a random food item index position and add the food item to the game grid. This function is recursive to prevent the food item from being added in a position occupied by the snake. If the random index is on the snake, the createFood function is called again to get another random index position. Our wait utility function prevents the recursive function from being called too often by pausing the function for 100 ms before each recursive function call.

Let's modify our startGame function so that the food items are cleared at the start of the game, the score is reset and a food item is created. Add the following lines to the startGame function, above the interval = setInterval(gameLoop, intervalTime); line:

  cells[foodItemIndex].classList.remove('food-item');
  cells[foodItemIndex].innerText = '';
  createFood();
  score = 0;
  scoreDisplay.innerHTML = score;

Now we need to detect if the food item is eaten and if so, add a new food item to the game grid. Add the following lines to the gameLoop function, above the cells[currentSnake[0]].classList.add('snake'); line:

  if (cells[currentSnake[0]].classList.contains('food-item')) {
    cells[currentSnake[0]].classList.remove('food-item');
    cells[tail].classList.add('snake');
    snakeColor += snakeColorIncrement % 360;
    cells[tail].style.background = `hsl(${snakeColor}, 100%, 50%)`;
    currentSnake.push(tail);
    score++;
    scoreDisplay.textContent = score;
    createFood();
  }

The food item is 'eaten' by checking if the snakes head position cell contains the food item. If it does, we remove the 'food-item' class to remove the food item. We increase the snake's length by adding a new segment to the tail end of the snake. Then we increase the score, and create a new randomly positioned food item.

The food items increase in size when they are added as we added a scale transform to the food-item class in the style.css file.

Our snake game is almost complete! The last thing we need to do is make it mobile-friendly by making the on-screen arrow buttons functional.

Making the game mobile-friendly

Add the following lines near the bottom of the script.js file, just above the existing event listeners.

function handleButtonKeyMove(e) {
  const { id } = e.currentTarget;
  moveSnake(id);
}
keyBtns.forEach(keyBtn => {
  keyBtn.addEventListener('mousedown', handleButtonKeyMove);
  keyBtn.addEventListener('touchstart', handleButtonKeyMove);
});

For each key button, we add two event listeners: "mousedown" and "touchstart". We use the handleButtonKeyMove function to handle these events. We get the id attributes of the on-screen buttons from the HTML id attributes that we added in the index.html file. These id attributes match the corresponding event key strings of the arrow keys on a keyboard. This makes it easy to pass the id string to the moveSnake function to handle the direction change.

Run your project. Our game is now complete. See how high you can get your score using either your keyboard or the on-screen buttons.

Next steps

Now that you have built a simple snake game with some basic styling, you might want to improve it or add extra features.

You can build your own by copying the code above, or by forking our example repl at replit.com/@ritza/snake-game-vanilla-javascript.

Here are some suggestions:

Make the snake transition from cell to cell a smooth animation.
Persist the top five highest scores by storing them in local storage. Create a pop dialog menu to view these high scores.
Increase the speed of the snake as the game progresses to make it harder.
Add obstacles.
Add sound effects.
Make different food items have different points.

You can also learn how to make Snake with Kaboom. Kaboom.js is a JavaScript game programming library that makes creating games like this easy.

Creating a Discord meme-maker bot with Python

RitzaCo — Tue, 12 Jul 2022 08:17:23 +0000

In this tutorial, we'll create a Discord bot that adds captions to images, allowing server members to create memes. Users will call the bot using a command and supply it with an image file and a caption. The bot will reply with a new image file that includes the caption.

By the end of this tutorial, you will:

Use discord.py to create a bot that can be added to any Discord server.
Understand the basics of image processing and dealing with files in memory using Python.
Know how to host Discord bots on Replit!

Getting started

Creating a Discord application

Open another browser tab and visit the Discord Developer Portal. Log in with your Discord account, or create one if you haven't already. Keep your repl open – we'll return to it soon.

Once you're logged in, create a new application. Give it a name, like "ImageCaptioner".

Discord applications can interact with Discord in several different ways, not all of which require bots, so creating one is optional. That said, we'll need one for this project. Let's create a bot.

Click on Bot in the menu on the left-hand side of the page.
Click Add Bot.
Give your bot a username (such as "ImageCaptionBot").
Click Reset Token and then Yes, do it!.
Copy the token that appears just under your bot's username.

The token you just copied is required for the code in our repl to interface with Discord's API. Return to your repl and open the Secrets tab in the left sidebar. Create a new secret with DISCORD_TOKEN as its key and the token you copied as its value.

Once, you've done that, return to the Discord developer panel. We need to finish setting up our bot.

First, disable the Public Bot option – the functionality we're building for this bot will be highly specific to our server, so we don't want anyone else to try to add it to their server. What's more, bots on 100 or more servers have to go through a special verification and approval process, and we don't want to worry about that.

Second, we need to configure access to privileged Gateway Intents. Depending on a bot's functionality, it will require access to different events and sources of data. Events involving users' actions and the content of their messages are considered more sensitive and need to be explicitly enabled.

For this bot to work, we'll need the "Message Content Intent", which will allow our bot to see the content of users' messages. Toggle it to the on position and save changes when prompted.

Now that we've created our application and its bot, we need to add it to a server. We'll walk you through creating a test server for this tutorial, but you can also use any server you've created in the past, as long as the other members won't get too annoyed about it becoming a bot testing ground. You can't use a server that you're just a normal user on, as adding bots requires special privileges.

Open Discord.com in your browser. You should already be logged in. Then click on the + icon in the leftmost panel to create a new server. Alternatively, open an existing server you own.

In a separate tab, return to the Discord Developer Portal and open your application. Then follow these steps to add your bot to your server:

Click on OAuth2 in the left sidebar.
In the menu that appears under OAuth2, select URL Generator.
Under Scopes, mark the checkbox labelled bot.
Under Bot Permissions, mark the checkboxes labelled Read Messages/View Channels, Send Messages, and Attach Files.
Scroll down and copy the URL under Generated URL.
Paste the URL in your browser's navigation bar and hit Enter.
On the page that appears, select your server from the drop-down box and click Continue.
When prompted about permissions, click Authorize, and complete the CAPTCHA.
Return to your Discord server. You should see that your bot has just joined.

Now that we've done the preparatory work, it's time to write some code. Return to your repl for the next section.

Writing the Discord bot code

We'll be using Discord.py to interface with Discord's API using Python. Add the following code scaffold to main.py in your repl:

import os, discord
from discord.ext import commands

DISCORD_TOKEN = os.getenv("DISCORD_TOKEN")

bot = commands.Bot(command_prefix="!")

@bot.event
async def on_ready():
    print(f"{bot.user} has connected to Discord!")

bot.run(DISCORD_TOKEN)

First, we import some Python libraries we'll need, including Discord.py and its commands extension. We then retrieve the value of the DISCORD_TOKEN environment variable, which we set in our repl's secrets tab above. Following that, we instantiate a Bot object. We'll use this object to listen for Discord events and respond to them. For the most part, we'll be responding to commands - messages from users which start with ! (the command_prefix we specified when creating our Bot object).

However, the first event we're interested in is not a command. The on_ready() event will trigger when our bot logs on to Discord (the @bot.event decorator ensures this). All this event will do is print a message to our repl's console, telling us that the bot has connected.

Note that we've prepended async to the function definition – this makes our on_ready() function into a coroutine. Coroutines are largely similar to functions, but may not execute immediately, and must be invoked with the await keyword. Using coroutines makes our program asynchronous, which means it can continue executing code while waiting for the results of a long-running function, usually one that depends on input or output. If you've used JavaScript before, you'll recognize this style of programming.

The final line in our file starts the bot, providing DISCORD_TOKEN to authenticate it. Run your repl now to see it in action. Once it's started, return to your Discord server. You should see that your bot user is now online.

Receiving user input

The Discord.py commands extension allows us to define command handlers using the @bot.command decorator. Without this, we'd have to manually parse the content of all user messages to determine whether a command had been issued, as was necessary for our role assignment bot tutorial. Let's define our main command now, !caption. Enter the following code below the definition of on_ready():

@bot.command(name="caption", brief="Add a caption to an image.", help="""Add a caption to an attached image. Example:

!caption "Hello world!" <attached image>

Supported image types: PNG, JPEG, WebP
             """)
async def caption(ctx, caption_text):
    pass

The @bot.command decorator will ensure that our function is invoked when a user types a message starting with !caption. We also use it to define some help text – the commands extension provides a default !help command, and each command we define can have two types of explanatory text:

brief: A short description of the command that will show alongside other defined commands when the user types !help.
help: A longer description of the command that will show when the user types !help name_of_command.

Our caption function takes two parameters:

ctx: This is the invocation context, a special object containing information such as the user who called the command, the server it was called in, and the files attached to the calling message, if any. All commands must take this parameter.
caption_text: This will be a string containing the caption the user wants to add to their image.

We'll start the body of the function with some user-friendly error handling. Replace pass with the function body shown below:

async def caption(ctx, caption_text):
    # Must have caption text
    if not caption_text:
        await ctx.message.reply("Please include some caption text after the `!caption` command. For example `!caption \"Hello world!\"")
        return

If the user forgets to include a caption in their command, they'll receive a reply informing them of this omission.

Next, we'll make sure they've attached a file to their command message with the following code:

    # Must have a file attached
    if ctx.message.attachments:
        image_url = ctx.message.attachments[0].url
    else:
        await ctx.message.reply("Please attach an image for me to caption.")
        return

If no file is attached, ctx.message.attachments will be an empty list and we'll send an error message to the user and abort the function. Otherwise, we'll store the URL of the first file attached to the message in image_url and continue execution. It's possible to attach multiple files to a single Discord message, but for this bot, we're going to ignore all but the first one.

Next, we need to check whether the attached file is an image. We'll do this by determining the file's MIME type using Python's built-in mimetypes library. Add the following line to the top of your main.py file:

import mimetypes

We now need to specify which MIME types we'll support. According to our help text, images for captioning should be PNGs, JPEGs, or WebPs. These are the most common non-animating image types on the web, so we shouldn't need to support any more for the moment. Add the following code below the definition of DISCORD_TOKEN:

SUPPORTED_MIMETYPES = ["image/jpeg", "image/png", "image/webp"]

Return to the caption() function. Add the following code below the block of code that checks whether a file is attached to the user's message:

    # File must be an image
    if mimetypes.guess_type(image_url)[0] not in SUPPORTED_MIMETYPES:
        await ctx.message.reply("Sorry, the file you attached is not a supported image format. Please upload a PNG, JPEG or WebP image.")
        return

The mimetypes.guess_type function will determine what kind of file we're dealing with from its URL. If we don't find its filetype in our list of supported types, we'll send an error message to the user and cease execution.

Now that we've dealt with the most likely error cases, it's time to handle a correctly formatted !caption command. First, we need to fetch the image file – we have a URL for it, so we can use Python's requests library for this. Add the following line to the top of your main.py file:

import requests

Then return to the bottom of the caption function and add the following code:

    # Fetch image file
    response = requests.get(image_url)

    # Store image file name
    image_filename = ctx.message.attachments[0].filename

We use a GET request to retrieve the user's image and store its filename in another variable.

It would be convenient if we could deal with this image completely in memory, without saving it to a file. We can do this by treating the image as a binary stream, provided by Python's built-in io library. Add the following line to the top of main.py:

from io import BytesIO

Return to the bottom of the caption function and add the following:

    # Caption image
    final_image = caption_image(BytesIO(response.content), caption_text)

BytesIO will convert the image from HTTP response content into a binary stream, which is similar to the file object returned by open(). This allows us to work with the image as though it were a file without ever saving it to disk.

We'll write the caption_image() function in the next section. It takes an image and a caption and returns an image with the caption applied. Once we've got that implemented, we'll return to this function and send the finished image back to the user.

Captioning images

The code we're going to write in this section is quite different from the Discord API code above, so we'll put it in a separate file. That way, we can easily reuse it for other applications – for example, we might also want to write a Telegram bot, a command-line application, or even a small website that adds captions to images. By separating our code, we can implement any of these later on without having to change or even think about the image captioning logic.

Create a new file named caption.py and populate it with the code below:

from PIL import Image, ImageDraw, ImageFont
from io import BytesIO

def caption_image(image_file, caption, font="impact.ttf"):
    img = Image.open(image_file)

We're using the Pillow library for image processing. This library is imported as PIL because it's a fork of an earlier, discontinued project of that name. This library has a wealth of image manipulation features, one of which is adding text to images.

To install Pillow, open pyproject.toml and add it to [tool.poetry.dependencies] as shown below:

[tool.poetry.dependencies]
python = ">=3.8.0,<3.9"
numpy = "^1.22.2"
replit = "^3.2.4"
discord = "^1.7.3"
pillow = "^9.1.1" # <-- new line

Stop and run your repl to update its dependencies and install the new package. Normally we would let Replit do this for us, but later in this section, we're going to test caption.py without linking it to the Discord code in main.py, so Replit won't have a chance to detect and install our new package on its own.

Return to caption.py. Below our imports, we define the caption_image() function used in main.py. In addition to the image file and caption parameters, we'll add the ability to optionally specify a font, defaulting to Impact, a popular font for making memes. Download the font file now and upload it to your repl.

We start the caption_image() function by creating an Image object from the file provided as an argument. Next, we'll need to convert our Image into an ImageDraw so that we can add text to it. We'll do that with the following line of code, inserted below the definition of img:

    draw = ImageDraw.Draw(img)

Next, we need to load our font:

    font_size = int(img.width/16)
    font = ImageFont.truetype("impact.ttf", font_size)

We use ImageFont.truetype() to load a TrueType font from a file. We specify the font size in the second argument. Users will be able to upload different-sized images, so rather than hardcoding a specific font size, we've expressed the size in terms of the image's width, allowing it to scale appropriately. Feel free to experiment with this value.

Now that we've got our image and font, we can start drawing. Extend your function as follows:

    caption_w, caption_h = draw.textsize(caption, font=font)

    draw.text(((img.width-caption_w)/2, (img.height-caption_h)/8), # position
              caption, # text
              (255,255,255), # color
              font=font, # font
              stroke_width=2, # text outline width
              stroke_fill=(0,0,0)) # text outline color

The ImageDraw.textsize() method returns the height and width of a given string in a given font. We need this information to place our caption in the upper center of the image.

The ImageDraw.text() method actually draws our text. We provide it with our text and the necessary positioning and coloring information. To avoid situations where text blends in with the background, we make our text white with a black outline. Again, feel free to experiment with different colors, outlines and positions.

Our work here is done, and all that remains is to return the image. But before we do that, let's test this code out on its own. Add the following line to the bottom of your function to save the image to a file:

    img.save("output.png")

Find an image you'd like to add a caption to. If you don't have one on hand, use this picture of a robot. Upload your chosen image to your repl.

At the bottom of caption.py, outside of the definition of caption_image(), add the following line:

caption_image("replbot.png", "Hello world!")

Change the image file to your file's name and the caption to whatever you want. Then, in your repl's shell, type python caption.py and press Enter. A file named output.png should appear in your repl's file pane. Click on it to see the results of the code we've just written. Our version looks like this:

Returning captioned images

Now we'll tie everything together. Once you're happy with the text size and colors of your captions, delete the caption_image() function invocation from the bottom of caption.py and replace the line that reads img.save("output.png") with the following:

    with BytesIO() as img_bytes:
        img.save(img_bytes, format=img.format)
        content = img_bytes.getvalue()

    return content

Instead of saving our image to a file, we save it to a binary stream object, much like we did when fetching the original image from Discord. We keep the image format the same as the original using Pillow's Image.format attribute. We then convert our BytesIO stream into a bytes object with .getvalue() and return it to the caller.

Open main.py and import caption_image() from caption.py with the following line near the top of the file, below your other imports:

from caption import caption_image

Return to the bottom of the caption() function definition. Add the following code below the definition of final_image:

    # Send reply
    await ctx.message.reply(file=discord.File(BytesIO(final_image), filename=f"captioned-{image_filename}"))

This code will reply to the user with a message containing the image we created above.

Stop and run your repl, and then switch to your Discord server. Enter a message such as !caption "Hello world!" and attach an image to it. You should receive a reply something like this:

Text wrapping

Our bot works reasonably well for short captions, but anything longer than about five words goes off the edges of the image.

We can fix this by splitting caption text into multiple lines. We'll use Python's textwrap library to do this. Open caption.py and add the following line to the top of the file:

import textwrap

Then add the new line shown below to the caption_image() function.

    font_size = int(img.width/16)
    font = ImageFont.truetype("impact.ttf", font_size)

    # NEW LINE BELOW
    caption = textwrap.fill(text=caption, width=img.width/(font_size/2))
    # NEW LINE ABOVE

    caption_w, caption_h = draw.textsize(caption, font=font)

    draw.text(((img.width-caption_w)/2, (img.height-caption_h)/8), # position
              caption, # text
              (255,255,255), # color
              font=font, # font
              stroke_width=2, # text outline width
              stroke_fill=(0,0,0)) # text outline color

Here, textwrap.fill() will return a new version of our caption string with newline characters (\n) inserted in appropriate places to ensure that each line of the text contains no more than width characters. It will do this without splitting words over multiple lines.

We use the following calculation to get width:

img.width / (font_size / 2)

This is the width of the image divided by half the font size. Most of the characters in the Impact font are taller than they are wide, so dividing the font size by two gives us reasonably good results for most text. It should also work for other fonts that aren't extremely wide. Try experimenting with different maximum line lengths.

Rerun your repl now and return to Discord to try out some different long captions.

Where next?

Our image captioning bot is functional but quite rudimentary. If you'd like to continue working on it, here are some ideas you might want to try:

More font and text color options. You could implement these as additional bot commands.
The ability to add two captions to an image, on both the top and bottom.
A different interface for your image captioning code, such as a Telegram bot or a simple website.
Pillow provides a number of filters that you could apply to images in addition to captioning them.
If you would like to make the text wrapping more robust for different fonts, you could try rewriting that part of caption.py. You might find this gist and this article helpful.

Discord bot code can be hosted on Replit permanently, but you'll need to use an Always-on repl to keep it running 24/7.

You can find our repl below:

https://replit.com/@ritza/ImageCaptionBot

Building a 3D obstacle avoiding game with three.js

RitzaCo — Mon, 11 Jul 2022 12:30:00 +0000

Three.js is a general-purpose 3D library for browsers. You can use it to create 3D objects, animations, and games. Take a look at the three.js examples page in the documentation to see what kind of things you can make.

In this tutorial, you will learn the basics of three.js and its game creation capabilities by making a simple obstacle avoiding 3D game. In the game, you will control a box that moves through a 3D course. The goal of the game is to avoid the obstacles and get to the end of the course.

We will create the game in Replit, which is an online integrated development environment (IDE). This means that you can do this tutorial in the browser, and it will be easy to share your game online.

Creating a new project in Replit

Head over to Replit and create a new repl. Choose HTML, CSS, JS as your project type. Give this repl a name, like "3D obstacle avoiding game".

Importing three.js to the project

Open the script.js file in your repl. We'll import three.js by referencing it from a content distribution network (CDN) to get us up and running quickly. Add the following line to the script.js file to import three.js from the Skypack CDN:

import * as THREE from 'https://cdn.skypack.dev/three@0.140.2';

The import keyword is used to import a JavaScript module. It will not work as is – we need to indicate that this script file is a module. To make this work, change the default script tag in the index.html file to the following:

<script type="module" src="script.js"></script>

The type=module attribute allows us to use module features in our script.

Now we are ready to use three.js in our project.

Creating a scene with the player box

To display 3D objects on the screen, we need three things: a scene, a camera, and a renderer. Then we will place 3D objects in the scene. Most objects also require lighting to be added to see them.

Let's start by creating a scene and adding a camera. Add the following lines to the script.js file:

const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(
  70,
  window.innerWidth / window.innerHeight,
  0.1,
  200
);

This creates a scene. The scene determines what will be rendered and where it will be rendered. We will add objects, a camera, and lights to our scene.

We are using a perspective camera, which is the most commonly used camera type for 3D scenes. Perspective cameras use perspective projection, which mimics the way human eyes see. The further away objects are from the camera, the smaller they appear.

The four parameters of the PerspectiveCamera constructor function define the camera's viewing frustum, which is the field of view of our camera in the 3D world. The parameters are:

fov - Field of view, the camera frustum vertical field of view, in degrees.
aspect - Camera frustum aspect ratio.
near - Camera frustum near plane, in world units.
far - Camera frustum far plane, in world units.

The above image shows the camera's viewing frustum. The viewable objects are between the near and far plane. There are two objects in the frustum, a purple stick and an orange stick. The sticks are the same size. The dotted lines show how the sticks are projected onto the near plane, which shows how they will be seen. Their size on the near plane is different. The orange stick, which is further away from the camera, appears smaller. The units used are world units, it can be mapped to any defined unit but it is usually in meters.

Next, we will position our camera in the 3D world and make it look at a specific point. The parameters are the x, y, and z points in the 3D world. Add the following lines of code to the script.js file:

camera.position.set(4, 4, -4);
camera.lookAt(0, 0, 2);

Let's add a renderer so that we can display the scene. We will attach it to a DOM element on our web page. Add the following lines of code:

const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setSize(window.innerWidth, window.innerHeight);
renderer.render(scene, camera);
document.body.appendChild(renderer.domElement);

This creates a new renderer that will display our scene using WebGL. WebGL (Web Graphics Library) is used for rendering complex graphics, such as 3D scenes, on the web. It does this by accessing the graphics card on the user's device. The antialias property is used to determine if anti-aliasing will be used, which is a method that smooths jagged edges on objects. This makes our 3D world look better. The size of the renderer is set to the browser width and height using the setSize method so that our scene will take up the entire browser window. We then call the renderer's render method to tell the renderer to draw the scene using our created scene and camera. We then add the renderer DOM element, which is a <canvas> element, to the HTML document. The renderer uses the <canvas> element to display the scene.

Now let's create our first 3D object, the player box. This will be the box that we move around in the game. In three.js, we need three things to create an object:

Geometry - An object contains the x, y, z points that make up a shape.
Material - The surface of the geometry. Gives the geometry color and texture.
Mesh - Geometry + material. This is what we will add to our scene.

Add the following lines above the renderer declaration:

const geometry = new THREE.BoxGeometry(1,1,1);
const material = new THREE.MeshBasicMaterial({ color: 0xe56956 });
const mesh = new THREE.Mesh(geometry, material);

The 0x in front of the color property value means that it is a hexadecimal value. Most materials require a light source to bounce off of them so that they can be seen. The MeshBasicMaterial does not.

Now let's add the mesh to the scene:

scene.add(mesh);

Run the code now by pushing the "Run" button at the top of the Replit window. You should see your first scene, an orange cube:

The MeshBasicMaterial does not look 3D. It would be better to have a material that light can interact with so that we can get some depth to our player box. Replace your material with the following material:

const material = new THREE.MeshLambertMaterial({ color: 0xe56956 });

The MeshLambertMaterial is a relatively simple material that can reflect light. Your player box will not be visible now, we need to add a light source. We will add an ambient light and a directional light.

Add the following lines to the script.js file, above the renderer:

const ambientLight = new THREE.AmbientLight(0xffffff, 0.6);
const directionalLight = new THREE.DirectionalLight(0xffffff, 0.6);
directionalLight.position.set(10, 20, 0);
scene.add(ambientLight, directionalLight);

We add a white directional light that is set along the x-, y-, and z-axes so that it shines on the top and side of the box. The ambient light allows us to see the box better from all angles. The first parameter for the light constructor functions is the color, and the second parameter is the light intensity, which ranges from 0 to 1. You should be able to see your player box now. It will look more 3D, as each side has different lighting. You can use your browser dev tools to check the console logs if you encounter any errors.

Let's also get rid of the window scrollbars. Add the following to the style.css file in the body selector:

overflow: hidden;
margin: 0;

Your player box should now look like this:

Try changing the material color, light intensity, and camera position to see what happens.

Before we get our player box moving, let's change our code so that it is nicely structured for the game logic that we will add. Add the following lines to the top of the script.js file:

let camera, scene, renderer, player;
const boxSideLength = 0.5;

init();

The camera, scene, and renderer variables are global variables so that they are available throughout our script. They will be defined in functions we create. Remove the const keyword in front of their declarations that we already added.

We also initialize a player variable for our created box.

The boxSideLength variable is for the x, y and z lengths of our box. Most of our boxes will be squares.

Now let's define the function called init. This function will be used to initialize the game, by rendering and setting up the scene and creating our objects. Define an init function and move the camera, light, and renderer code into it:

function init() {
  scene = new THREE.Scene();
  camera = new THREE.PerspectiveCamera(
    70,
    window.innerWidth / window.innerHeight,
    0.1,
    200
  );

  camera.position.set(4, 4, -4);
  camera.lookAt(0, 0, 2);

  const ambientLight = new THREE.AmbientLight(0xffffff, 0.6);
  const directionalLight = new THREE.DirectionalLight(0xffffff, 0.6);
  directionalLight.position.set(10, 20, 0);
  scene.add(ambientLight, directionalLight);

  initializeBoxes();

  renderer = new THREE.WebGLRenderer({ antialias: true });
  renderer.setSize(window.innerWidth, window.innerHeight);
  renderer.render(scene, camera);
  document.body.appendChild(renderer.domElement);
}

We also call the initializeBoxes function, which we will soon define.

Now let's make a createBox function. We will use this function to create our player box, and later to create obstacles. Define the createBox function and move the code for creating your player box inside of it:

function createBox(x, y, z) {
  const geometry = new THREE.BoxGeometry(
    boxSideLength,
    boxSideLength,
    boxSideLength
  );
  const material = new THREE.MeshLambertMaterial({ color: 0xe56956 });
  const mesh = new THREE.Mesh(geometry, material);
  mesh.position.set(x, y, z);
  scene.add(mesh);
}

The geometry definition now uses the boxSideLength variable to set the lengths of the sides. There is one extra line of code here, the call to the mesh.position.set function. This will set the position of the created box in the 3D world based on the arguments passed to the function. This will be useful when we create randomly positioned obstacles.

Now let's create an initializeBoxes function that will be used to create all of the boxes at the start of the game. Add the following lines of code:

function initializeBoxes() {
  player = createBox(0, 0, 0);
}

All this function currently does is create a player box that is positioned in the center of our 3D world. Its x, y, and z positions will be 0. If you run your repl code, you should still be able to see your box.

Animating the player box

In the final game, the player box moves continuously along the z-axis. We will make use of an animation loop to continuously move the player box and re-render the scene to see the movement. At the bottom of the script.js file, add the following lines:

function animate() {
  player.mesh.position.z += speed;
  camera.position.z += speed;

  renderer.render(scene, camera);
  requestAnimationFrame(animate);
}

The animate function will be called on every frame by using the requestAnimationFrame function, which is a web API that is used to create animations. It will call the animate function before each repaint of the screen by the browser. The number of function calls is usually 60 per second.

For each animate function call, we move the player box and the camera by changing their position along the z-axis. The camera will follow the player box. Let's add a global speed variable at the top of our script.js file so that we can easily change it later if we want to:

let speed = 0.10;

To access the player box's mesh property, let's return the mesh property from the createBox function. Add the following to the end of the createBox function:

  return {
    mesh,
  };

We also need to call our animate function initially to get it started. In the init function, add the following line below renderer.render(scene, camera):

animate();

Our player box will now be moving, but we won't be able to see the movement. We are going to add a GridHelper so that we can see the movement. A GridHelper is an object that defines a grid, which is a two-dimensional array of lines along the x- and y-axes. This will give our 3D world a 2D grid surface. In the init function, add the following lines below initializeBoxes():

  const gridHelper = new THREE.GridHelper(200, 200);
  scene.add(gridHelper);

You will now be able to see your player box move through the 3D world.

If you wait long enough, the box will move off the grid. Let's restrict the movement of the box so that it can't move off the grid.

Creating a game course

The first thing we will do to prevent the player box from moving off the grid will be to add another box, the finishing line box. The finishing line box will be added at the boundary of the grid. Our game course will be from the center of the grid to the end of the grid, along the z-axis. Later, we will add collision detection to check if our player box has hit the finishing line box so that we can end the game before the player box leaves the grid.

We will create a new global variable called courseLength that will define the distance to the edge of the grid. Our player box starts moving from the center of the grid (x = 0, y = 0, z = 0) so our square grid's length should be double the course length. We will also restrict the movement of the box along the x- and y-axes. Add the following global variables to the top of the script.js file:

const courseLength = 100;
const gridHelperSize = courseLength * 2;

// limit movement of player box on x and y-axis 
const xBoundary = 4 - (boxSideLength / 2);
const yBoundary = xBoundary / 4;

We set the courseLength to 100 world units. We use the gridHelperSize to define the length of our square grid along the x- and z-axes. The xBoundary and yBoundary variables are used to limit the movement of our player box along the x- and y-axes.

Let's update the gridHelper to use the gridHelperSize variable for its size and number of divisions parameters:

  const gridHelper = new THREE.GridHelper(gridHelperSize, gridHelperSize);

Now we will add the finish line box. Add the following to the initializeBoxes function:

  // create finish line box
  const geometry = new THREE.BoxGeometry(
    xBoundary * 2,
    yBoundary * 2,
    boxSideLength
  );
  const material = new THREE.MeshLambertMaterial({ color: "green" });
  const mesh = new THREE.Mesh(geometry, material);
  mesh.position.set(0, 0, courseLength);
  scene.add(mesh);

This creates a green box that is positioned at the end of the grid. It marks the end of the game course. It's positioned at the end of the course where the z-axis value is equal to the course length. The size of the box along its x- and y-axes marks the x and y boundary. We will restrict the player box's movement so that it can't move past the finish line box. Its size along the x- and y-axes is double the boundary length, because it needs to mark the negative and positive axis boundaries.

You will now be able to see the finish line box at the end of the grid. To reach the end of the grid sooner, you can change the speed variable.

Controlling the player box

Let's add some controls so that we can move our player box up, down, left, and right. Add the following lines to the bottom of the script.js file:

// moving player box with arrow keys
window.addEventListener("keydown", (e) => {
  const key = e.key;
  if (key === "ArrowLeft") {
    player.mesh.position.x += speed;
  }
  if (key === "ArrowRight") {
    player.mesh.position.x -= speed;
  }
  if (key === "ArrowUp") {
    player.mesh.position.y += speed;
  }
  if (key === "ArrowDown") {
    player.mesh.position.y -= speed;
  }
});

This creates an event listener that listens for a key press event. The player box's mesh (geometry + material) position is increased or decreased along the x- or y-axis, depending on which arrow button is pressed. Run your repl now and you should be able to move your player box with the arrow keys. You will notice that you can move off the screen, and when you reach the edge of the grid, you can avoid hitting the finish line box. Let's restrict the movement of the player box so that it always hits the finish line box. Replace the event listener that you just added with the following code:

window.addEventListener("keydown", (e) => {
  const key = e.key;
  const currXPos = player.mesh.position.x;
  const currYPos = player.mesh.position.y;
  if (key === "ArrowLeft") {
    if (currXPos > xBoundary) return;
    player.mesh.position.x += speed;
  }
  if (key === "ArrowRight") {
    if (currXPos < -xBoundary) return;
    player.mesh.position.x -= speed;
  }
  if (key === "ArrowUp") {
    if (currYPos > yBoundary) return;
    player.mesh.position.y += speed;
  }
  if (key === "ArrowDown") {
    if (currYPos < -yBoundary) return;
    player.mesh.position.y -= speed;
  }
});

Here we add some extra lines of code to restrict the movement of the player box along the x- and y-axes by getting the current x and y position of the player box and then preventing movement if the position exceeds the current boundary values that we set using our global variables xBoundary and yBoundary.

Note that if you increased the speed variable to reach the end of the course sooner, you may need to increase the width and height of the finish line box to ensure that the player box always hits it, as the player box will be able to move a bit more along the x- and y-axes.

Detecting collisions

To determine that we have reached the end of the course, we need to be able to detect collisions. Once the player box has collided with the finish line box, the game is over. Add the following global variables to the top of your script.js file:

let gameOver = false;
const numOfObstacles = 0;
var obstaclesBoundingBoxes = [];

The gameOver flag variable will be used to determine when the game is over. This will occur once the finish line is reached, or if the player box collides with an obstacle (we will add obstacles later). The number of obstacles is currently zero. The obstaclesBoundingBoxes will store a set of x, y, and z positions of bounding boxes that describe the positions of all of our objects, excluding the player box. We will use these bounding boxes to detect collisions.

In the initializeBoxes function, add the following lines at the bottom:

  const boundingBox = new THREE.Box3().setFromObject(mesh);
  obstaclesBoundingBoxes.push(boundingBox);

This will create a bounding box for the finish line box mesh object. We add this to the obstaclesBoundingBoxes array. The Box3 object represents a bounding box in 3D space. It describes a set of coordinates, it does not appear in our 3D world. We use the setFromObject method to calculate the bounding box of the finish line box, using the finish line box's mesh. Within the bounding box object, there is a max and min property that describes the upper and lower x, y, and z boundaries of the box. For example, the bounding box of the finish line box contains the following max and min properties:

max: {x: 3.75, y: 0.9375, z: 100.25}
min: {x: -3.75, y: -0.9375, z: 99.75}

Now let's create a function to detect collisions. Add the following function below the createBox function:

function detectCollisions() {
  const playerBox = new THREE.Box3().setFromObject(player.mesh);
  // Check each object to detect if there is a collision
  for (let i = 0; i < numOfObstacles + 1; i++) {
    // an object was hit
    if (obstaclesBoundingBoxes[i].intersectsBox(playerBox)) {
      gameOver = true;
      alert("You win!");
      return;
    }
  }
}

To detect a collision, we first create a bounding box for the player box by creating a Box3 object. We then loop through the obstaclesBoundingBoxes array and use the intersectsBox method to check for an intersection – a collision – between the playerBox and each obstacle. We currently don't have any obstacles, so we can only check for a collision with the finish line box. Given that we will always hit the finish line box, we set gameOver to true once it is hit. We will use an alert to let the player know that they have won when they reach the end of the course.

We need to call the detectCollisions function in the game loop animate function so that we constantly check for a collision. Change your animate function so that it is the same as the animate function below:

function animate() {
  if (gameOver) return;
  player.mesh.position.z += speed;
  camera.position.z += speed;

  detectCollisions();

  renderer.render(scene, camera);
  requestAnimationFrame(animate);
}

The if statement at the start of the animate function prevents the function from running if the game is over.

Let's also add if (gameOver) return; to the start of the "keydown" window.addEventListener callback function to disable the keyboard event if the game is over.

You will now get a "You win!" alert message once you reach the finish line box at the end of the grid.

Creating obstacles

Now let's add some obstacles for the player box to avoid to make it a game. Set the numOfObstacles global variable to 50. We are going to write a createObstacle function to generate 50 randomly positioned obstacles. Add the following function below the createBox function:

function createObstacle() {
  const x = THREE.MathUtils.randFloatSpread(xBoundary * 2);
  const y = THREE.MathUtils.randFloatSpread(yBoundary * 2);
  const z = THREE.MathUtils.randFloat(10, courseLength - boxSideLength);
  const obstacle = createBox(x, y, z);
  const boundingBox = new THREE.Box3().setFromObject(obstacle.mesh);
  obstaclesBoundingBoxes.push(boundingBox);
}

We make use of some math utility functions of the three.js MathUtils object to get random x, y, and z points along our course. These will be used to randomly position obstacles. We get random x and y points using our x and y boundaries. The randFloatSpread function takes in a range parameter and returns a random float in the interval [- range / 2, range / 2]. We get a random z value using the randFloat function. It takes in a low and high parameter and returns a random float in the interval [low, high]. This value is always positive, as our course is positioned on the positive side of the z-axis. The low value starts at 10, as we don't want to place obstacles right in front of or on the player box. The high value is the courseLength, so that the obstacles can be positioned all along our course. We subtract the boxSideLength to prevent the obstacles from being placed on the finish line box. We then pass these x, y, and z points to the createBox function to create an obstacle box. A bounding box is created for each created obstacle, and added to the obstaclesBoundingBoxes array so that we can detect collisions between our player box and the obstacles.

We need to call the createObstacle function to create the obstacles. In the initializeBoxes function, let's add a for loop to create the obstacles:

function initializeBoxes() {
  player = createBox(0, 0, 0);

  for (let i = 0; i < numOfObstacles; i++) {
    createObstacle();
  }

  ...

}

This will create 50 randomly positioned obstacles. Run your repl to see them:

Each time you reload the page, the obstacles will be randomly positioned.

Adding win-or-lose logic

Try to collide with an obstacle, and you will see that the alert message is always "You win!". Let's fix that by adding some win-or-lose logic. In the detectCollisions function, replace the for loop with the following for loop:

  for (let i = 0; i < numOfObstacles + 1; i++) {
    // an object was hit
    if (obstaclesBoundingBoxes[i].intersectsBox(playerBox)) {
      gameOver = true;
      if (i !== numOfObstacles) {
        alert("You lose");
      } else {
        // the last box is the finish line box
        alert("You win!");
      }
      return;
    }
  }

The last object bounding box in the obstaclesBoundingBoxes array is the finish line box. Knowing this, we can determine when the player box has reached the finish line without hitting an obstacle. If the player box intersects with the last item in the obstaclesBoundingBoxes array, you win. If the player box intersects with any other item, you lose.

The game is now playable. Try make it to the end of the obstacle course.

Adding restart

There is one big problem with our game: once the game is over we need to refresh the page to play again. That's not a very good user experience. Let's add a "Play" button that will show on page load and when the game is over. It will start the game and reset everything that needs to be reset at the start of a game.

Add the following to the index.html file inside of the <body> tag to create a button and a screen that covers the window behind the button:

    <div id="play-btn-screen">
      <div class="play-btn-container">
        <div>Use the up, down, left and right arrow keys to move</div>
        <button id="play-btn">Play</button>
      </div>
    </div>

Add the following to the style.css file:

#play-btn-screen {
  position: absolute;
  min-width: 100%;
  min-height: 100%;
  display: flex;
  align-items: center;
  justify-content: center;
  z-index: 1;
}

.play-btn-container {
  color: white;
  text-align: center;
}

#play-btn {
  background-color: red;
  padding: 1rem 1.5rem;
  margin: 0.5rem;
}

This will create a play button in the middle of the screen.

Now let's make the button work. Add the following global variables to the top of the script.js file:

const playBtnScreen = document.getElementById("play-btn-screen");
const playBtn = playBtnScreen.querySelector("#play-btn");
var allObjs = [];

This gets the play button screen (background cover behind the button) and play button element from the DOM and stores them in variables. The allObjs array will store all of the created objects. We need this array to clear the scene by removing all of the objects at the start of each game. We do this so that we can place new randomly positioned objects in the scene and not have objects in the scene from previous rounds.

Next, add a new click event listener on the playBtn. Add the following to the bottom of the script.js file:

playBtn.addEventListener("click", () => {
  allObjs.forEach((obj) => scene.remove(obj));
  camera.position.set(4, 4, -4);
  camera.lookAt(0, 0, 2);
  initializeBoxes();
  gameOver = false;
  animate();
  playBtnScreen.style.visibility = "hidden";
});

The play button is used to start and also re-start the game. The first thing we do when the play button is clicked is to remove all the objects in the scene using the scene.remove method. We then reset the camera position and call the initializeBoxes function, which creates and positions all of the objects. We set gameOver to false so that our animate function and keydown event listener will work. We then call the animate function to start the animation loop, and then we hide the play button screen, which hides the play button as well. We need to make a few more changes in our script.js file for the play button to work properly:

Delete the animate() function call in the init function. We now call it when the play button is clicked.
Add allObjs.push(mesh); in the createBox function above scene.add(mesh);. This adds the created box mesh (object) to the allObjs array.
Add the following lines in the detectCollisions function below gameOver = true;:

    playBtnScreen.style.visibility = "visible";
    playBtn.focus();

This will make our play button visible at the end of the game and focus the button so that you can easily restart the game by pressing the spacebar or enter key.

Add the following lines at the start of the initializeBoxes function:

    // make empty at start of a game
    allObjs = [];
    obstaclesBoundingBoxes = [];

This clears the allObjs array so that it only contains objects created in the current game. We also clear the obstaclesBoundingBoxes as we only want to detect collisions with objects in the current game.

Add allObjs.push(mesh); in the initializeBoxes function above scene.add(mesh);. This adds the finish line box to the allObjs array.

Our game is almost complete, all we need to do now is make it mobile-friendly.

Making the game mobile friendly: Adding on-screen arrow buttons

To make the game mobile friendly, we will add up, down, left, and right buttons to the bottom of the screen.

Add the following to the index.html file inside the <body> tag, just above the <script> tag to create the buttons:

  <div id="keys">
    <div class="keys-container">
      <button id="up">
        <svg width="30" height="30" viewBox="0 0 10 10">
          <g transform="rotate(0, 5,5)">
            <path d="M5,4 L7,6 L3,6 L5,4" />
          </g>
      </svg>
      </button> 
      <button id="left">
        <svg width="30" height="30" viewBox="0 0 10 10">
          <g transform="rotate(-90, 5,5)">
            <path d="M5,4 L7,6 L3,6 L5,4" />
          </g>
        </svg>
      </button> 
      <button id="down">
        <svg width="30" height="30" viewBox="0 0 10 10">
          <g transform="rotate(180, 5,5)">
            <path d="M5,4 L7,6 L3,6 L5,4" />
          </g>
        </svg>
      </button> 
      <button id="right">
        <svg width="30" height="30" viewBox="0 0 10 10">
          <g transform="rotate(90, 5,5)">
            <path d="M5,4 L7,6 L3,6 L5,4" />
          </g>
        </svg>
      </button> 
    </div>
  </div>

The up, down, left, and right icons are created using SVGs.

Now let's add some basic styling to our buttons. Add the following to the style.css file:

#keys {
  position: absolute;
  min-width: 100%;
  min-height: 100%;
  display: flex;
  align-items: flex-end;
  justify-content: center;
}

.keys-container {
  display: grid;
  grid-template-columns: 50px 50px 50px;
  grid-template-rows: auto;
  grid-template-areas:
    ".    up   ."
    "left down right";
  grid-gap: 10px;
  padding-bottom: 3rem;
}

#keys button {
  padding: 0.5rem;
}

#up {
  grid-area: up;
}

#down {
  grid-area: down;
}

#left {
  grid-area: left;
}

#right {
  grid-area: right;
}

To see the arrows, click the "Open in a new tab" button in the repl Output tab. This opens the link to the repl in a new tab. You can copy this link to view your repl on your phone or to share it with your friends.

You should now be able to see the screen arrow buttons.

Try clicking a button before pressing "Play". You will notice that you can't click the arrow buttons. This is because the play button screen, which covers the whole screen, has a CSS z-index property of 1. Once you click "Play", the play button screen CSS visibility property is set to hidden, and you will be able to press the arrow buttons.

Now let's add some JavaScript click event listeners and some functions to make our arrow buttons work on desktop and mobile. Our code is going to look quite complex because we use some extra functions and setTimeout to allow the player box to continuously move when the arrow button is held down. This makes for a better user experience than having to continuously tap or click the button to move in one direction. Add the following global variable to the top of the script.js file:

const keyBtns = document.querySelectorAll(".keys-container button");

This gets all the key buttons from the DOM and stores them in a variable.

Now add the following to the bottom of the script.js file:

let timeoutID = 0;

function moveLeft() {
  const currXPos = player.mesh.position.x;
  if (currXPos > xBoundary) return;
  player.mesh.position.x += speed;
  clearTimeout(timeoutID);
  timeoutID = setTimeout(moveLeft, 50);
}

function moveRight() {
  const currXPos = player.mesh.position.x;
  if (currXPos < -xBoundary) return;
  player.mesh.position.x -= speed;
  clearTimeout(timeoutID);
  timeoutID = setTimeout(moveRight, 50);
}

function moveUp() {
  const currYPos = player.mesh.position.y;
  if (currYPos > yBoundary) return;
  player.mesh.position.y += speed;
  clearTimeout(timeoutID);
  timeoutID = setTimeout(moveUp, 50);
}

function moveDown() {
  const currYPos = player.mesh.position.y;
  if (currYPos < -yBoundary) return;
  player.mesh.position.y -= speed;
  clearTimeout(timeoutID);
  timeoutID = setTimeout(moveDown, 50);
}

function handleKeyDown(e) {
  if (gameOver) return;
  const { id } = e.currentTarget;

  if (id === "left") {
    moveLeft();
  }
  if (id === "right") {
    moveRight();
  }
  if (id === "up") {
    moveUp();
  }
  if (id === "down") {
    moveDown();
  }
}

// moving box - mobile - using screen btns
keyBtns.forEach((keyBtn) => {
  keyBtn.addEventListener("mousedown", handleKeyDown);
  keyBtn.addEventListener("touchstart", handleKeyDown);
  keyBtn.addEventListener("mouseup", () => {
    clearTimeout(timeoutID);
    timeoutID = 0;
  });

  keyBtn.addEventListener("mouseleave", () => {
    clearTimeout(timeoutID);
    timeoutID = 0;
  });
  keyBtn.addEventListener("touchend", () => {
    clearTimeout(timeoutID);
    timeoutID = 0;
  });
  keyBtn.addEventListener("touchcancel", () => {
    clearTimeout(timeoutID);
    timeoutID = 0;
  });
});

For each key button, we add "mousedown" and "touchstart" event listeners. When the button is clicked or touched, the handleKeyDown function is called. This function determines which button was clicked or touched by checking the ID of the event's currentTarget property. Different functions are called depending on the ID of the button. For each function that handles the movement in a particular direction, we get the current position of the player box, check if it is within the set boundaries, and increase or decrease its position by the speed variable value. We then recursively call the function again after 50 ms using setTimeout so that the movement is continuous when the button is held down.

The setTimeout function returns a timeoutID that is a positive integer value. It identifies the timer created by the call to setTimeout(). This value is passed to clearTimeout() to cancel the timeout after each recursive function call so that we don't create unnecessary timeouts.

For each key button, we also add "mouseleave", "touchend", and "touchcancel" event listeners. These clear the timeouts when the button is not held down anymore.

A little cheat in the game: If you have a touchscreen laptop, pressing the arrow key on your keyboard and on the screen will make it move faster than normal!

Save and run your project. Our game is complete!

Next steps

We learnt the basics of three.js and built a simple 3D game. There are many things that you can do to improve the game. Here are some you might want to try:

Replace the alert with a nicely styled modal.
Style the objects, or import or create 3D models. See rendering 3D scenes with three.js for more information.
Add a nicer surface instead of the grid.
Add a loading screen while the 3D scene is loading.
Make the game more challenging by increasing the speed the player box moves at as the game progresses, adding more obstacles, or by making the obstacles move.
Add a points system. Change the game logic so that you have to hit the boxes to get points.
- Store the points in local storage.
Add physics to the collisions using cannon-es.
Or for a more advanced challenge: Make a bigger course, try making infinite movement within finite bounds so that you don't use too much of your computer's memory.

You can find our repl below:

https://replit.com/@ritza/3D-obstacle-avoiding-game