Description

A balloon race without the balloons: no litter, no harm to wildlife, and supporters can follow their balloon live. Virtual Balloon Race is made for schools, PTAs, clubs and charities.

Supporters buy an entry in your WooCommerce shop, name their balloon, choose its colour and helium strategy, and can add their own logo or launch point. When the race launches, every balloon drifts across a live map on real wind data, and a leaderboard ranks them by how far they get from the launch point.

For supporters

A live preview of their balloon on the product page as they choose its colour, name, team and logo
A live map with each balloon’s trail; tap a balloon to follow it
A leaderboard with search and paging, team standings, and “My balloons” for logged-in entrants
Emails when the race launches and when it finishes, with each balloon’s final position
My Account My balloons, and “Track your balloon” links on order pages and emails

For organisers

Schedule races: entries open, launch, end; or press Launch now / Finish now on the day
A tracking page and a ready-to-sell “Balloon Race Entry” product are created for you
Paid extras: tactical helium strategy, custom launch point, logo upload
Optional teams (e.g. houses or classes), scored by average, total or best distance
Optional entry limits, with “Only N places left!” and “Sold out” in the shop
Three flight modes: Drift (true to life), Soar (the default) and Jetstream (maximum distance)
Refunded, cancelled or failed orders take their balloons out of the race automatically
Withdraw or reinstate balloons by hand, mark bursts, advance the race, export a CSV
Public names are shown as first name and last initial

The map uses Leaflet (bundled with the plugin) and OpenStreetMap. Wind comes from Open-Meteo. No API keys are needed; busier or commercial sites can add keys for paid map and weather providers. See External services below.

External services

This plugin can connect to the third-party services below. Nothing is contacted until the site admin allows it: on a new site, external services are off, and the plugin’s admin screens ask once whether to allow them (or tick Allow external services in Balloon Race Settings Maps, weather and place search). Until then, maps show the balloons without a background map, balloons follow the default heading instead of the live wind, and place search is hidden. The free services need no API keys or accounts; the same Settings section can switch to keyed providers for busier or commercial sites.

Sponsor views and clicks are only counted if the site admin turns it on (Settings Data). They are counted by your own site (totals only, no cookies, IP addresses or other visitor data), and nothing is sent to any other service.

Open-Meteo (weather)

Used to move balloons with the real wind. When a race is flying, your server requests the current wind speed and direction for the areas the balloons are in (rounded latitude and longitude) each time balloons move. No personal data is sent; requests identify only the plugin and its version. With an Open-Meteo API key set, requests go to customer-api.open-meteo.com and include the key.
Service: open-meteo.com. Terms of use. The free API is for non-commercial use; for commercial use, get an API key.

Map tiles: OpenStreetMap, MapTiler, Stadia Maps or a custom provider

Used to draw the map. Visitors’ browsers load map images from the chosen provider whenever a map is shown (public race map, Settings, race screen, and the launch point picker on the product page), which shares their IP address and browser details with that provider. With a keyed provider, the key is part of each image address.

OpenStreetMap (default): tile.openstreetmap.org. Tile usage policy. Privacy policy.
MapTiler (optional): api.maptiler.com. Terms. Privacy policy.
Stadia Maps (optional): tiles.stadiamaps.com. Terms. Privacy policy.
Custom: whatever tile address the site admin enters.

Place search: Nominatim or MapTiler

Used by the “search for a place” box when choosing a launch point (in Settings, on the race screen, and for buyers choosing a custom launch point). When the Search button is pressed, the text typed is sent from the visitor’s browser to the chosen service (at most one search a second). Place search can be switched off.

Nominatim (default): nominatim.openstreetmap.org. Usage policy. Privacy policy.
MapTiler (optional, with MapTiler map tiles): api.maptiler.com. Terms. Privacy policy.

Screenshots

The live race map with balloon trails, team filter and the balloon list.

Team standings and the leaderboard, with paging and search. — The live race map with balloon trails, team filter and the balloon list.

Installation

Install and activate WooCommerce (needed to sell entries; the map and leaderboard work without it).
In Plugins Add New Plugin, upload the plugin zip, then activate Virtual Balloon Race.
The plugin creates a Balloon Race page (map, team standings, leaderboard, race list) and a Balloon Race Entry product (£3). Change the product’s name, price and picture like any product.
Go to Balloon Race Races Add race: set when entries open, the launch time, an optional end time and the launch point.
Check Balloon Race Settings: flight mode, how often balloons move, add-on prices, teams, and more.

For on-time updates on a quiet site, add a real server cron that runs wp lvbr tick every few minutes (WordPress only runs scheduled jobs when someone visits).

FAQ

Does it need WooCommerce?: To sell entries, yes. Without WooCommerce, the map and leaderboard still work for balloons you add.
Where does the wind come from?: From Open-Meteo’s free weather API, for the area each balloon is in, so balloons that spread apart follow different winds. If the wind can’t be fetched, balloons follow a default heading.
Can I try it before selling entries?: Yes: Balloon Race Settings Demo race Create a demo race makes a race with 30 made-up balloons that have already flown for three days. It renews itself: when it’s about to end, a fresh one replaces it (untick Keep it running to stop that). Remove it from the same place.
How far do the balloons go?: It depends on the wind and the flight mode. In Soar (the default), a week-long race typically sees the leader several hundred to about a thousand kilometres from the launch point. Settings shows an estimate for each mode.
Who wins?: By default, the balloon furthest from its launch point in a straight line, as in real balloon races. Each race can instead rank by the whole distance travelled.
Will the entry product show in my shop before a race is planned?: No. It’s only listed (shop, categories, search, product blocks, sitemap) once a race is planned, and can only be bought while that race is taking entries. Its own page still opens and says when entries open.
What happens if an order is refunded or cancelled?: Its balloons are withdrawn: they leave the map, leaderboard and team scores, but stay in the admin screens and the CSV for your records. Reopening the order brings them back.
Can I turn the emails off?: Yes. They’re WooCommerce emails: switch each off, or change its wording, in WooCommerce Settings Emails.
What is kept if I delete the plugin?: Everything, unless you tick Settings Data Delete all race data when the plugin is deleted. Pages, products, orders and uploaded logos are always kept.

Reviews

There are no reviews for this plugin.

Contributors & Developers

“Lumaha Virtual Balloon Race” is open source software. The following people have contributed to this plugin.

f3zz3h

Translate “Lumaha Virtual Balloon Race” into your language.

Interested in development?

Browse the code, check out the SVN repository, or subscribe to the development log by RSS.

Changelog

2.0.0

Changed: the plugin is now called Lumaha Virtual Balloon Race, and its code, data, hooks, shortcodes, REST routes and WP-CLI commands use the lvbr prefix (e.g. [lvbr_map], /lvbr/v1/, wp lvbr). Existing sites are moved over automatically on the next page load, including shortcodes in pages and widgets.
Changed: update these by hand, as they are not moved over automatically: shortcodes in theme files or page builders ([balloon_…] [lvbr_…]), custom code using vbr_ hooks or /vbr/v1/ routes, .vbr- CSS, theme email template overrides, and cron jobs running wp vbr tick (now wp lvbr tick).
Changed: external services (map tiles, live wind, place search) are off on new sites until the admin allows them, and sponsor view and click counting is off until turned on. Sites upgraded from 1.x keep both on.
Changed: admin notices only appear on the screens they relate to.

1.18.0

New: each race can have its own movement settings (update interval, speed, helium multipliers, variance and burst chances) under Movement on its race screen. Blank boxes use the Settings value, so a short demo and a week-long race can run side by side.
Changed: automatic updates run as often as the most frequent race needs, and each race moves on its own interval. Without race settings, nothing changes.

1.17.1

Fix: on themes that add products to the basket in the background (AJAX), a chosen logo was silently left out. The form now posts normally when a logo is chosen, and if the logo still doesn’t arrive the buyer is told instead of losing it.
Changed: coding-standards tidy-up; every direct database query is on the plugin’s own tables and now says so.

1.17.0

New: big races (over 300 balloons) load a much lighter map: only the leaders’ trails, the viewer’s own and the selected balloon’s, with other trails loaded when a balloon is clicked. A 5,000-balloon race drops from about 2.3 MB to 150 KB.
New: map refreshes that find nothing new are answered “not modified”, saving data on every poll.
Fix: in races of 1,000 or more balloons, rank numbers in the map list overlapped the balloon icons.

1.16.2

Fix: with the plugin active, other products (such as Simple products) lost the General tab, and so their price fields, in the product editor.
Changed: tidied for WordPress.org’s Plugin Check (no errors); releases include a WordPress.org build.
New: a race-day checklist in the documentation.

1.16.1

Changed: the entry product is only listed in the shop, search, product blocks and the sitemap once a race is planned. Its own page still opens and says when entries open.

1.16.0

New: sponsor views and clicks. Each sponsor’s card shows how often they were shown on the race pages and how often their links were clicked, with a CSV download per race. Only totals are kept: no cookies or visitor data.

1.15.0

New: sponsor hot-air balloons. A sponsor’s own hot-air balloon flies with the race on the same live wind but is never ranked. Three styles: stripes with a name band, a logo panel, or the logo filling the balloon. Headline sponsors fly a large one.
New: a branded launch flag, labelled with the sponsor’s name and linking to them.

1.14.0

New: race sponsors. Add sponsors to each race (name, website, logo, tier: Headline, Gold, Silver or Supporter) and choose where each appears: “presented by” the race, a leaderboard strip, a map badge, the sponsor wall ([balloon_sponsors]) and a line in the launch and results emails. Sponsor links are marked as sponsored.
New: prizes per race (1st–5th place, best team, random draw or your own), each optionally donated by a sponsor. Shown as cards on the tracking page ([balloon_prizes]), as “Up for grabs” on the product page, and with their winners in the results email.
Changed: the default tracking page now includes the prizes and the sponsor wall (pages you’ve edited are left alone).

1.13.0

New: big races (over 500 balloons) page and search the leaderboard on the server, so the page stays light with thousands of entries. Smaller races work as before.
Changed: “My balloons” and the Yours badges now count balloons bought while logged in, or on orders that belong to the account. Account and billing emails, which aren’t verified, no longer claim balloons (developers can restore this with the vbr_match_balloons_by_email filter).
Tested: entries for two races open at the same time.

1.12.1

Fix: in block themes (such as Twenty Twenty-Five), the balloon preview now replaces the product image, instead of appearing at the top of the page with the placeholder image still showing.
Fix: the entry form’s fields are styled consistently, so the balloon name box is no longer flat in block themes.

1.12.0

New: Settings Maps, weather and place search. Choose the map tiles (OpenStreetMap, MapTiler, Stadia Maps or a custom tile server, with an API key), the place search (Nominatim, MapTiler or off) and an Open-Meteo API key for commercial use.
Changed: place searches are spaced at least a second apart, as Nominatim’s usage policy asks.
Changed: the plugin’s author is Luke Hart, with the project site as the plugin’s home page.

1.11.0

The plugin’s code is now public on GitHub: https://github.com/f3zz3h/virtual-balloon-race

1.10.0

New: optional entry limit per race, with “Only N places left!” and “Sold out” in the shop. Unpaid orders hold their places.
New: Leaflet is bundled with the plugin instead of loaded from a CDN.
New: Settings link on the Plugins screen.
New: readme.txt for WordPress.org.
New: Settings Demo race creates a ready-made race with made-up balloons (also wp vbr demo), and replaces it with a fresh one when it’s about to end.

1.9.0

New: abandoned logo uploads are deleted after 7 days.
New: optional “Delete all race data when the plugin is deleted” (Settings Data).
New: translation template.

1.8.0

New: emails to entrants when a race launches and when it finishes.

1.7.0

New: refunded, cancelled and failed orders withdraw their balloons; Withdraw / Reinstate by hand.

1.6.0

New: flight modes (Drift, Soar, Jetstream).
New: leaderboard paging, 10 per page by default.

1.5.0

New: balloons are ranked by distance from the launch point by default; each race can rank by distance travelled.
New: a Balloon Race Entry product is created on a fresh install.
Fix: the race screen no longer fails when WooCommerce is inactive.

1.4.0

New: optional teams with team standings.
New: live balloon preview on the product page; one balloon per basket line.
New: balloon-shaped map markers, with logos filling the balloon.

1.3.0

New: “Balloon race entry” product type, tracking page, My Account My balloons, “My balloons” on the map and leaderboard.

1.2.0

New: race schedules (entries open, launch, end) and per-race sales.