Frog-Hopper-2D
2D game made to practice collision detection and movement. Get the frog across the lanes of traffic to the Pond.
Requirements
- a C++ compiler (
g++)
make- the SDL2 and SDL2_image development packages, which on Debian/Ubuntu are:
sudo apt-get install libsdl2-dev libsdl2-image-dev
A VS Code dev container that installs these is provided under .devcontainer/.
Building
make
This writes an executable named frogHopper_executable to the repository root. make clean removes it.
Running
./frogHopper_executable
The game resolves its assets against the directory holding the executable, so resources/ must sit next to frogHopper_executable. The default build satisfies this because both end up in the repository root. The working directory the game is launched from does not matter.
A window titled "Frog Hopper" opens at 1000x750.
How to play
The frog is controlled with the four arrow keys. Movement continues while a key is held and stops when it is released.
Four cars cross the screen, two travelling right and two travelling left. Each car reappears on the far side once it has left the screen.
- Touching a car ends the run and shows the lose screen.
- Moving the frog off the top of the screen shows the win screen.
From either end screen, releasing any key returns to the game, and closing the window exits. A key that was already held when the screen appeared counts too, so letting go of an arrow key held into a car or across the top dismisses the screen straight away.
Play then picks up where it stopped: the frog goes back to the bottom of the screen, standing still in the column it was in, and the cars carry on from where they were. Each return starts a new attempt, so the crossing time (see "High scores" below) counts again from the frog's next move.
Downloads
Each release from v1.1.0 on carries a Windows x64 zip and a Linux x64 tarball, each with a .sha256. The Linux build needs the system's SDL2 and SDL2_image (sudo apt-get install libsdl2-2.0-0 libsdl2-image-2.0-0); the Windows zip carries its DLLs. How releases are made: docs/RELEASING.md.
Play in your browser
The game also runs in a web browser, built with Emscripten:
On a keyboard the arrow keys work as in the desktop game. On a phone or tablet, four on-screen arrow buttons appear under the game; hold one to keep moving, or tap it for a short hop. They also leave the win and lose screens. The browser version does not send usage reports.
To build it, install and activate the Emscripten SDK, then run:
web/build.sh
This writes index.html, index.js, index.wasm, index.data (the preloaded resources/) and arcade-scores.js (see below) to web/build/. Serve that directory over HTTP to play it locally, e.g. python3 -m http.server --directory web/build 8000 and open http://localhost:8000. The page itself is web/shell.html. The Browser build workflow builds it on every pull request and every push to master. It deploys to https://frog-hopper.play.danielstephenson.dev only on a push to master while the repository variable ARCADE_ENABLED is true, or when the workflow is run by hand; the runs a pull request triggers never deploy.
High scores
In the browser version, a signed-in player's crossing times go to the "Fastest crossing" leaderboard (fastest-crossing, lower is better) of arcade-social at https://api.play.danielstephenson.dev. A crossing is timed in game time: the frames from the frog's first move of the attempt until it reaches the pond, at 60 frames a second, in seconds to two decimals (holding up from the start, about 3.13 s, is the fastest possible). Every crossing is sent and the service keeps each player's best. Two achievements are unlocked too: first-win (the first crossing) and under-five (a crossing under five seconds).
Sign-in happens on arcade-social's own page; the game never sees a password, and nothing is sent while signed out, from any address other than https://frog-hopper.play.danielstephenson.dev, or from the desktop game (the calls are compiled only under __EMSCRIPTEN__). Scores are reported by the player's browser and can be forged, so the board is labelled "not verified". The client is web/arcade-scores.js, vendored unchanged from arcade-social's clients/js; web/build.sh copies it next to the page, web/shell.html loads it, and src/FrogHopper.cpp calls it through EM_JS. Its calls never throw: a refused or lost score is dropped and the game carries on.
Usage reporting
The game reports to trace by default: one startup event per launch, carrying the program name (Frog-Hopper-2D), its version from version.txt, and a random installation ID. Nothing about you, your machine or the game is sent (the trace server sees the IP address of the request, as every web server does).
The first run prints one line saying so on stderr and writes a small settings file, usage-reporting.conf, to $XDG_CONFIG_HOME/Frog-Hopper-2D/ (by default ~/.config/Frog-Hopper-2D/; ~/Library/Application Support/Frog-Hopper-2D/ on macOS, %APPDATA%\Frog-Hopper-2D\ on Windows). To turn reporting off:
- set
enabled=false in that file, or
- set
TRACE_USAGE_REPORTING=off or DO_NOT_TRACK=1 in the environment (this turns it off for every trace-reporting program, and nothing is printed or written).
The installation ID is a random UUID, made the first time reporting is on and kept in trace-install-id in $XDG_DATA_HOME/frog-hopper-2d/ (by default ~/.local/share/frog-hopper-2d/; ~/Library/Application Support/frog-hopper-2d/ on macOS, %APPDATA%\frog-hopper-2d\ on Windows). It is not derived from anything about you or your machine; it only lets trace count installations rather than launches. Delete the file to reset it. Setting TRACE_INSTALL_ID sends that value instead, and the file is left alone. Every opt-out above also stops the ID: with reporting off, the file is never created, read or sent.
The event is sent in the background by the vendored trace-client-cpp header (src/header/trace_client.hpp) through the system curl; if curl is missing or the machine is offline, nothing is sent and the game is unaffected. FROG_HOPPER_2D_USAGE_REPORTING_ENDPOINT points reporting at another server, e.g. a local one while testing. An endpoint= line in the settings file does the same, and the environment variable wins when both are set. Details: https://github.com/Stephenson-Software/trace#usage-reporting
License
This project is licensed under the Stephenson Software Non-Commercial License (Stephenson-NC). See LICENSE.
