Upgrading to 2.0.0: the plugin's internal names changed from vbr to lvbr (WordPress.org needs a prefix of at least four characters) and it's now called Lumaha Virtual Balloon Race. The update moves everything over on the next page load: tables, settings, order and product data, the entry product type, shortcodes in pages and widgets, and scheduled updates. Things outside the database need changing by hand: shortcodes typed into theme files or page builders ([balloon_map] → [lvbr_map], and the same for the others), custom code using the vbr_ hooks or /vbr/v1/ REST routes (now lvbr_ and /lvbr/v1/), CSS aimed at .vbr- classes (now .lvbr-), email template overrides in a theme (now lvbr-balloon-launched.php and lvbr-balloon-results.php) and server cron jobs running wp vbr tick (now wp lvbr tick). Sites upgraded from 1.x keep external services and sponsor counting switched on.

Deleting the plugin keeps all race data unless Settings → Data → Delete all race data when the plugin is deleted is ticked. Its scheduled jobs always stop.

Translations: languages/lumaha-virtual-balloon-race.pot is the translation template (refreshed in every release zip; the text domain is lumaha-virtual-balloon-race). Translate it with Poedit or Loco Translate, or put lumaha-virtual-balloon-race-<locale>.mo in wp-content/languages/plugins/.

Moving from a hand-copied folder (e.g. wp-content/plugins/VirtualBaloonRace/): the zip installs to wp-content/plugins/virtual-balloon-race/, which WordPress treats as a different plugin, so don't run both. Deactivate the old one, delete it (the plugin has no uninstall routine, so this removes only its files; races, balloons, settings and pages stay in the database), then upload and activate the zip.

2. Check the settings

Balloon Race → Settings holds the rules shared by every race:

Timing: WordPress only runs scheduled jobs when someone visits the site. On a quiet site, updates can arrive late, though balloons still catch up on the next run. For on-time updates, add a real server cron that runs wp lvbr tick every few minutes.

3. Create a race

Balloon Race → Races → Add race

A race goes through four stages on its own:

Each race's page has Launch now and Finish now buttons for event-day control. A race can only be deleted while it has no balloons.

You can schedule several races. Usually only one runs at a time, but overlapping races work too.

Teams (optional)

With Enable teams ticked in Settings, each race has its own teams on its race screen: new races start with the default teams, and you can rename, recolour, add or remove them (a team with balloons can't be removed). Add default teams fills a race that has none, and Team scoring can override the default for that race. A race with no teams runs without them.

When a race has teams, buyers must pick one. Team standings appear on the tracking page, the leaderboard and map show each balloon's team, and the map can be filtered to one team. Scores: average and total use every balloon in the team (burst balloons count at the distance they reached); best is the team's furthest balloon. Switching teams off hides them everywhere but keeps them.

Prizes (optional)

The race screen's Prizes panel lists what's up for grabs: 1st to 5th place, best team, a random draw, or your own label (e.g. "Furthest Eco-Glide"), each with a description and an optional Donated by sponsor (one of this race's saved sponsors). Prizes show:

• on the tracking page, as cards ([lvbr_prizes], part of the default page; pages still on an earlier default get it on upgrade, edited pages are left alone),
• on the product page as Up for grabs: …, when one race is taking entries,
• in the final-results email, with each prize's winner: the balloon in that place (public name only), the leading team, or "To be announced" for draws and your own prizes.

Sponsor links are marked rel="sponsored" and open in a new tab.

Sponsors (optional)

Each race can have its own sponsors (never site-wide), added on the race screen's Sponsors panel: name, website, logo (from the Media Library) and tier. Nothing is sold through the shop.

Change any sponsor's ticks (also: launch flag, map badge, leaderboard strip). Presented by, launch flag, map badge and leaderboard strip have one spot per race: on a clash the higher tier keeps it (between equal tiers, the one higher in the list), and the save notice says who lost it. Deleting a race removes its sponsors; their logos stay in the Media Library. Where they appear:

• Presented by: above the map (with the race name), in the leaderboard header and next to "Entering: …" on the product page
• Map badge: "Map supported by" with the sponsor's logo (or name) in the map's top-right corner, clear of the zoom buttons and the map credits
• Leaderboard strip: "Leaderboard brought to you by …" above the leaderboard
• Sponsor wall: [lvbr_sponsors], by tier (Headline large, Gold and Silver with logos, Supporters as names); part of the default tracking page
• Emails: one plain line in the launch and results emails, "This race was made possible by …"
• Hot-air balloon: the sponsor's own hot-air balloon flies with the race on the same live wind, from the launch point, but is never ranked, burst or counted in team scores. Headline sponsors fly a large one. Pick a style on the sponsor's card: stripes and name band (two colours and up to 12 letters), logo panel or logo fills the balloon (the logo styles need a logo; a very wide or tall logo is shown whole rather than cropped). On the map it has a popup with a link to the sponsor, a faint trail in its colour, and a "Sponsor" entry above the ranking in the side list
• Launch flag: the launch marker is labelled with the sponsor's name and links to them

Every sponsor link opens their website in a new tab and is marked rel="sponsored". Logos come from your Media Library; nothing is loaded from other sites.

Views and clicks (once Count sponsor views and clicks is ticked in Settings → Data). Each sponsor's card shows how often they were shown on the race pages and how often their links were clicked, and Download views and clicks (CSV) gives one row per sponsor and placement, handy for thanking sponsors after the race. The visitor's browser reports these (race pages are usually page-cached, so the server rarely sees a visit): one small request per page with the placements shown, and one per click. Only running totals are kept: no cookies, no IP addresses, nothing about who saw or clicked what. Each placement counts once per page view; emails and visitors without JavaScript (most bots) aren't counted. The numbers are a guide, not an audit: the reporting address is public.

4. Set up the balloon product

A fresh install creates a ready-to-sell Balloon Race Entry product (£3, published, any race taking entries) as soon as WooCommerce is active. It can only be bought while a race is taking entries, and it isn't listed in the shop, categories, search, product blocks, the [products] shortcode or the sitemap until a race is planned for it (upcoming or taking entries; for a product locked to one race, that race), so it's safe to leave published. Its own page still opens, saying no race is taking entries yet (or when entries open), so a link shared early still works. Change its name, price, description and picture like any product. Upgrades never add a product. Settings → Pages and products lists your entry products and offers Create entry product if there are none.

To sell a particular race separately: open the race (Balloon Race → Races → Edit) and click Create entry product. This makes a draft product locked to that race and opens it so you can set the price and publish.

Or create one by hand:

1. Products → Add New, and set Product data to Balloon race entry. Entries are always virtual, so there's no shipping.
2. Set the price (e.g. £3) on the General tab.
3. On the Balloon race tab, choose which race it sells:
   • Any race taking entries (default): buyers enter whichever race is open. If several are open, they pick one.
   • A specific race: the product only sells entries for that race.

The race's edit screen lists every product that sells its entries.

When no race is taking entries, the product can't be added to the basket and shows when entries next open. If a race launches while an entry for it is still in someone's basket, the entry is removed with a message.

Upgrading from 1.2: products marked with the old "Balloon Entry" tick box or balloon-entry tag are converted to the new type automatically. Products that weren't simple products (e.g. variable) can't be converted; a notice in admin lists them.

On balloon entry products, the product images are replaced by a live balloon preview: a balloon on a sky background that follows the buyer's choices (colour, uploaded picture, balloon name, team and helium strategy). To keep the normal product images, add add_filter( 'lvbr_product_preview', '__return_false' );.

Buyers fill in:

• Balloon name, colour and helium strategy (Balanced is free; Max Height and Eco-Glide cost the "tactical strategy" price)
• Optional custom launch point (+£2 by default): search or click a map to start from their school or hometown
• Optional logo or picture (+£2 by default): PNG, JPG or WebP up to 1 MB. It fills the balloon on the map; very wide or tall pictures are shown whole instead of cropped. The product page's balloon preview shows it as soon as it's chosen

Entries are sold one balloon per basket line: there's no quantity box on the product page or in the basket, because each balloon has its own name, colour and picture. After adding a balloon, the buyer sees "“Sky Rocket” is in your basket" with Design another balloon and View basket; the form keeps their race, team and colour and clears the name for the next one. Identical balloons can still be added as separate lines.

A balloon is created when its order reaches Processing or Completed.

5. The race tracking page

Activating the plugin creates a Balloon Race page (/balloon-race/) with the live map, team standings (when teams are on), the leaderboard and a list of races. It's ordinary page content (three shortcode blocks), so you can edit it, add text or rearrange it.

Balloon Race → Settings → Pages:

• Race tracking page: choose which page is the tracking page. Leaderboard names, My Account and order emails link to it.
• Create tracking page: shown when none is set (for example after the page was deleted).
• Regenerate page content: resets the page to the default map, leaderboard and race list. Your edits to that page are lost.

One page serves every race. /balloon-race/ shows the current race (the one flying, or else the next one taking entries, or else the next upcoming one, or else the last one finished). /balloon-race/?race=summer-2026 shows a particular race, and the race list links to each one. Links like /balloon-race/?race=summer-2026&balloon=12 open with that balloon selected.

Logged-in customers also get My Account → My balloons: each balloon they've entered, in every race, with its position, distance and a Track link.

Shortcodes

You can still build your own pages:

[lvbr_map]
[lvbr_leaderboard]
[lvbr_races]

On the map, clicking a balloon (or its name in the list or leaderboard) highlights its trail and fades the others. Click the map background to clear the highlight.

What entrants see

• Their own balloon. Logged-in entrants see their balloons marked Yours. The map opens on their best-placed balloon, the leaderboard pins Your balloons with each one's position, and both have an All balloons / My balloons toggle. A balloon counts as theirs if they bought it while logged in, or if its order belongs to their account (the orders listed under My Account → Orders, including guest orders WooCommerce has linked to the account). Typed-in account or billing emails don't claim balloons, because WooCommerce doesn't verify them; sites that verify emails can turn that back on with the lvbr_match_balloons_by_email filter.
• Guests get Track your balloon links on the order confirmation page and in their order emails.
• Search. The map list and the leaderboard both search by balloon name, owner or team. Leaderboard search covers every balloon in the race, not just the page being shown.
• Big races. Up to 500 balloons, the whole leaderboard is in the page, so paging and search are instant. Above that, the page holds only the first page of rows, and paging, search and My balloons ask the server (GET /lvbr/v1/leaderboard), so a race of thousands still loads quickly. Search matches the same things either way: balloon name, public owner name (first name and initial) and team. The map is lighter too: above 300 balloons it sends only the top 25 trails plus the viewer's own, and loads any other balloon's trail when it's clicked. A 5,000-balloon race drops from about 2.3 MB to 150 KB (gzipped), and refreshes that find nothing new are answered "not modified".
• Paging. The leaderboard shows 10 balloons per page by default, with page links and a Show … per page dropdown (10, 25, 50, 100 or All). A visitor's choice is remembered on their device. Search and My balloons page their results too. The admin leaderboard pages the same way, with its own dropdown.
• Owner names are shown publicly as first name and last initial ("Luke H."), on the map, the leaderboard and the REST API. Search only matches that short form. Admin screens and the CSV keep full names.

Refunds and cancellations

Balloons follow their orders:

• Cancelled, refunded or failed order: all of its balloons are withdrawn. They disappear from the map, leaderboard, team scores and API, and stop moving, but stay in the admin leaderboard and CSV marked Withdrawn (refunded), (order cancelled) or (payment failed).
• One line refunded (in WooCommerce's refund screen, with that line's quantity or total): just that balloon is withdrawn. A refund of an amount with no lines selected (e.g. a goodwill partial refund) leaves balloons alone.
• Order back to Processing or Completed, or a refund deleted: the balloons come back where they were.
• By hand: Withdraw / Reinstate on the admin leaderboard, e.g. for a duplicate or an unsuitable name. A balloon withdrawn by hand stays out even if its order changes.

Customers see withdrawn balloons in My Account → My balloons with the reason, and get no tracking link for them.

Emails to entrants

Two WooCommerce emails go to everyone with a balloon in a race (one email per person, listing all their balloons; withdrawn balloons are left out):

• Balloon race: launched, when the race launches (at its launch time, or Launch now): each balloon with a Track it link, and when the race ends.
• Balloon race: final results, when the race finishes (at its end time, or Finish now): each balloon's position, distance from launch (or travelled) and its team's finishing position, with a link to the final leaderboard.

Switch either off, or change its subject, heading and closing text, in WooCommerce → Settings → Emails. They use the shop's email header, footer and colours. Each race's screen shows whether its emails have gone out and to how many people. Emails are queued with WooCommerce's Action Scheduler and sent in the background, so large races don't slow the site. The plugin checks for launches and finishes hourly, after every movement update, and straight away on Launch now / Finish now. Upgrading to 1.8.0 marks races that have already launched or finished as emailed, so nothing old is sent. Theme overrides: copy templates/emails/lvbr-balloon-launched.php (or lvbr-balloon-results.php, and the plain/ versions) to yourtheme/woocommerce/emails/.

6. During the race

Balloon Race → Leaderboard (pick the race at the top):

• See every balloon, its owner's email, distance and status
• Advance now moves the race by a chosen number of hours, or by a fixed km range
• Mark burst / Undo burst and Withdraw / Reinstate for individual balloons
• Export CSV of the race's balloons and donors (with a Withdrawn column)

For developers

Layout

virtual-balloon-race.php        Bootstrap: constants, includes, activation, WP-CLI
includes/
  class-lvbr-install.php         Schema (dbDelta), version upgrades, Multisite installs
  class-lvbr-races.php           Race model: stages, lookups, save/delete, time helpers
  class-lvbr-balloons.php        Balloon table helpers, colours/strategies, trails, asset versions
  class-lvbr-settings.php        Settings screen + LVBR_Settings::get(); registers Leaflet
  class-lvbr-cron.php            Scheduling (Action Scheduler or WP-Cron) and the tick
  class-lvbr-weather.php         Open-Meteo wind, batched by ~11 km grid cell, cached in transients
  class-lvbr-geo.php             Great-circle destination / distance
  class-lvbr-map.php             REST API + [lvbr_map]
  class-lvbr-frontend.php        [lvbr_leaderboard], [lvbr_races] + frontend assets
  class-lvbr-pages.php           Tracking page: create on install, Settings → Pages, tracking_url()
  class-lvbr-account.php         My Account → My balloons
  class-lvbr-admin.php           Leaderboard admin page (per race)
  class-lvbr-admin-races.php     Races admin page
  class-lvbr-product-type.php    "Balloon race entry" product type, its admin tab, 1.2 → 1.3 product migration
  class-lvbr-product-balloon-entry.php  The product class (always virtual)
  class-lvbr-woocommerce.php     Balloon product fields, cart, order → balloon rows
  class-lvbr-race-entries.php    Race choice, purchasability, basket guard, race_id on balloons
  class-lvbr-teams.php           Teams: per-race lists, scoring, standings, the team editor
  class-lvbr-flight-modes.php    Flight modes (Drift, Soar, Jetstream): lift decay, landing, Settings cards
  class-lvbr-demo.php            Demo races (Settings → Demo race, wp lvbr demo)
  class-lvbr-housekeeping.php    Daily clean-up of abandoned logo uploads; basket check for removed logos
  class-lvbr-race-emails.php     Launch and results emails: when to send, who to, background queue
  emails/                       The two WooCommerce email classes (templates in templates/emails/)
  class-lvbr-order-sync.php      Withdraws / reinstates balloons when orders are refunded, cancelled or fail
  class-lvbr-team-entries.php    Team choice on the product page → basket → order → team_id on balloons
  class-lvbr-monetization.php    Paid add-ons: strategy fee, custom launch, logo upload
  class-lvbr-product-preview.php Live balloon preview in place of the product images
  class-lvbr-cli.php             wp lvbr …
assets/vendor/leaflet/          Leaflet 1.9.4 (BSD-2-Clause), bundled: no third-party CDN
assets/js/balloon.js            Balloon drawing (SVG) shared by the map and product page
assets/js/map.js                Public Leaflet map
assets/js/product.js            Product page launch picker + logo preview
assets/js/admin-settings.js     Launch-point picker (Settings and race form)
assets/js/admin-teams.js        Team list editor (Settings and race form)

Data

• {prefix}lvbr_races: one row per race. All times are stored in UTC. Stages are calculated from the clock and never stored.
• {prefix}lvbr_teams: one row per team, with race_id, name, color, sort. Races have team_scoring ('' = the Settings default).
• Flight modes (class-lvbr-flight-modes.php): each balloon stores flight_hours; a tick converts its hours into full-speed-equivalent hours by integrating the mode's half-life decay over the tick (so the update interval doesn't change the result), and Drift stops balloons after 36 flight hours. Races have flight_mode ('' = the Settings default).
• Distances: distance_km is the whole trail added up; from_start_km is the straight-line distance from the balloon's start (its custom launch point, else the race's), updated on every tick. Races have ranking ('' or from_start = distance from launch, travelled = distance travelled), and leaderboards, team scores and REST rank by that column.
• {prefix}lvbr_balloons: one row per balloon, with race_id, team_id, current latitude/longitude, start_lat/start_lng, trail_json (the most recent [lat, lng] points, capped by the trail-length setting), logo_attachment_id, has_custom_start, distance_km and is_burst.
• Settings: the lvbr_settings option. Tracking page: lvbr_tracking_page_id. Last tick per race: the lvbr_tick_summaries option.
• Upgrades run on plugins_loaded whenever lvbr_db_version is older than LVBR_DB_VERSION. Upgrading from 1.1 creates a first race and moves existing balloons into it. Steps that need WooCommerce or rewrite rules (product conversion, default pages, flushing rewrites) are queued in lvbr_pending_setup and run on the next init.

How a tick works

For each Flying race, a scheduled tick simulates the time since that race's last tick, counting from launch, stopping at the end time, and capped at 3× the interval. Each race uses its own interval and movement settings where it has them: the job runs at the shortest interval any unfinished race needs, and a race only moves when its own interval is due (races left on "Off" are manual only). For each balloon still flying:

1. Look up the wind for the balloon's grid cell. If that fails, use the wind at the launch point, then the default heading.
2. Travel bearing = wind direction + 180° (Open-Meteo reports where wind comes from), ±12° random jitter.
3. Distance = base speed × helium multiplier × hours × wind factor × (1 ± variance). The wind factor is a clamped blend of base speed and real wind speed.
4. Move to the new position, add it to the trail, then roll for bursts. Daily rates are converted to the tick length: 1 − (1 − daily)^(days).

Uncached grid cells are fetched in batches (up to 50 per request), and a failed lookup is remembered for 2 minutes. A lock stops two ticks running at once.

REST API (public, no auth)

Emails and order details are never included, and owners are first name + initial. Responses are sent with no-cache headers, including LiteSpeed's.

WP-CLI

wp lvbr tick                              # run due updates for every flying race (use from a system cron)
wp lvbr tick --race=<id|slug> --hours=6   # simulate hours for one race
wp lvbr races                             # list races, stages and balloon counts
wp lvbr status                            # schedule + last tick per race
wp lvbr demo [--balloons=30]              # create a demo race with made-up balloons
wp lvbr demo --remove                     # remove demo races

Hooks

Automated checks (GitHub Actions)

Every pull request and push to main runs:

• PHP syntax on PHP 7.4, 8.0 and 8.3, and WordPress Coding Standards (.github/workflows/php_check.yml). Rules are in phpcs.xml.dist; errors and warnings both fail the check. Queries on the plugin's own tables carry a targeted phpcs:ignore with the reason. Run it locally with composer install && composer phpcs.
• PHPStan static analysis at level 5 with WordPress and WooCommerce stubs (phpstan.neon.dist). Run it locally with composer install then composer phpstan. composer.json holds development tools only; the plugin itself has no Composer dependencies, and vendor/ isn't committed. phpstan-baseline.neon is empty; if the level is raised, record existing findings there so only new ones fail.
• Fresh install smoke test (.github/workflows/smoke_test.yml): installs the latest WordPress and WooCommerce, then tests/smoke/run.sh checks both activation orders (plugin before and after WooCommerce), the default page and product, a race end to end (purchasability, order → balloon, a tick, REST, teams), refunds and cancellations (line refund, refund deleted, goodwill refund, cancel and reopen, hand withdrawal, failed payment), the launch and results emails (one per person, withdrawn balloons left out, sent once, switched off in WooCommerce), housekeeping (abandoned logos, the basket check), entry limits (paid and unpaid places, sold out, basket limits, places freed), deleting the plugin with "Delete all race data" off and on and that the plugin logs no PHP errors. To run it by hand: set WP_PATH to a throwaway WordPress with WooCommerce and this plugin (as plugins/virtual-balloon-race) copied in, then bash tests/smoke/run.sh. It empties that site's database.

WordPress.org readme and donations

readme.txt is the plugin's WordPress.org listing (description, FAQ, External services, changelog). Keep Stable tag and the changelog in step with the version when releasing.

Donations go to https://buymeacoffee.com/lumaha: a Donate link on the Plugins screen and a short "Support this plugin" note at the foot of Settings (LVBR_Support::DONATE_URL in includes/class-lvbr-support.php, or the lvbr_donate_url filter; empty hides both), Donate link: in readme.txt, and GitHub's Sponsor button (.github/FUNDING.yml).

Releasing a version

1. On a branch, bump the version in the plugin header (Version:) and LVBR_VERSION in virtual-balloon-race.php (and LVBR_DB_VERSION if the schema changed). Merge it.
2. Tag main and push the tag: git tag v1.7.0 && git push origin v1.7.0.
3. The Release workflow (.github/workflows/release.yml) checks the tag matches the plugin version, builds the zip with .github/scripts/build-zip.sh and publishes a GitHub release with the zip attached and notes listing the merged pull requests.
4. Sites running 1.11.0 or later are offered the update within about 12 hours (includes/class-lvbr-github-updater.php reads the latest release through GitHub's API, cached for 12 hours; the plugin header's Update URI sends WordPress's update check there). A release must stay non-draft, non-prerelease and keep its virtual-balloon-race-<version>.zip asset, or it isn't offered.

.distignore lists the files left out of the zip (tests, CI, Composer and PHPStan files, docs/). Every pull request also builds the zip and offers it as a download (Checks → Release → Artifacts, kept 7 days), and the fresh-install smoke test installs from that same zip. Build one locally with bash .github/scripts/build-zip.sh (output in dist/).

WordPress.org listing images (.wordpress-org/, not in the zip): screenshot-1.png…screenshot-5.png in the order of readme.txt's Screenshots section, banner-772x250.png / banner-1544x500.png and icon-128x128.png / icon-256x256.png. WordPress.org puts the plugin's name over the bottom left of the banner, so keep that area clear. The deploy to WordPress.org uploads this folder as the listing's assets.

WordPress.org build: bash .github/scripts/build-zip.sh --wporg makes dist/virtual-balloon-race-<version>-wporg.zip without the GitHub update checker and the Update URI header, as WordPress.org requires (its plugins may only update from WordPress.org). Use it for the first submission; its folder, dist/wporg/virtual-balloon-race/, is what gets deployed to WordPress.org's SVN.

Testing locally

Any WordPress with WooCommerce will do (for example wp-env or the official Docker images). Copy the plugin in with the same exclusions as the zip:

rsync -rlt --delete --exclude-from=.distignore --exclude dist ./ /path/to/wp-content/plugins/virtual-balloon-race/
wp lvbr status
wp lvbr demo --balloons=10

scp -r into an existing folder creates a nested copy; use rsync. The fresh-install smoke test runs locally too: WP_PATH=/path/to/wordpress bash tests/smoke/run.sh (see the comments at its top).

Known gaps

How it works and why: docs/design.md. Before a real race: docs/race-day-checklist.md. Plans, bugs and ideas are tracked in GitHub Issues (milestones: Ready for wider use, WordPress.org listing). Not built yet:

• Balloons can drift over sea; there's no land awareness
• Wind is the 10 m wind speed and direction only (no gusts, rain or altitude bands)