BIOBUZZ simulator

A browser physics simulator for BIOBUZZ, the 2026-2027 FIRST Tech Challenge game, with the results of about 3,600 simulated matches. It is a project of the students and mentors of NCSSM FTC teams 5064, 8569, and 22377.

Live site: https://biobuzz.ncssmftc.org/

Page	What it is
Ten lessons	What to build, what to practice, and how to plan a match, with the numbers behind each lesson
Match Lab	Configure an alliance, and see its estimated score distribution and its chance of beating an opponent
Simulator	Four robots play a full match on the official field. Configure each robot, drive with a controller, and review and annotate the match.

This project isn't affiliated with or endorsed by FIRST. See NOTICE.md.

What the simulator models

• The field. The official field CAD supplies every field element. The HIVE is a rigid body on a pivot, calibrated to the six tipping cases of the Event Field Setup Guide, section 12.3. See docs/hive-calibration.md.
• The robots. A mecanum drivetrain with a DC motor model, a battery with internal resistance, and a traction limit. The intake, the launcher, and FLOWER placement are bulk models with sampled errors, not mechanism physics.
• The match. A full 2:30 MATCH with AUTO, the transition, TELEOP, scoring, ranking points, and a PIN referee (G421).
• The drivers. Every robot runs a scripted AUTO. In TELEOP, a planner or a person with a controller drives.

docs/simulator.md describes the planner, the AUTO scripts, partner coordination, the robot config, and the review mode.

Run it

You need Node.js 20 or later.

1. To install the dependencies, run npm install.
2. To start the dev server, run npm run dev.
3. Open the URL that Vite prints, go to Simulator, and then press Start match.

Input	Action
Left stick	Drive and strafe
Right stick X	Turn
LB and RB	Shoot NECTAR and shoot POLLEN
LT and RT	Place POLLEN and place NECTAR in a FLOWER
Gear icon, or a right-click on a robot	Open the robot config
Enter, R, C, M, V	Start, reset, change the camera, mark a moment, and review the match

To run the tests, run npm test. They cover the HIVE calibration, the drivetrain, the AUTO scripts, the referee, and full scripted matches, without a browser.

Run matches without a browser

Command	What it does
npx tsx scripts/match.ts	Plays one four-robot match and prints a timeline and the final score
npx tsx scripts/eval.ts LABEL	Plays 24 fixed seeds and reports the combined score and where TELEOP time goes
python3 scripts/eval-compare.py BASE NEW	Compares two evaluation runs
npx tsx scripts/exp-run.ts GROUP 12 11 101 TAG	Runs a group of robot designs from scripts/exp-specs.ts against the baseline
npx tsx scripts/exp-report.ts	Pools the design runs into tables
npx tsx scripts/auto-timeline.ts 1001	Prints the AUTO timeline of the red robots

The results are in experiments/. Every number on the site comes from a file there.

Repository layout

Path	Contents
src/sim/	The match simulation. It has no DOM and no three.js dependency, so it runs in Node.js.
src/auto/	The planner: tactics, path planning, the path follower, AUTO scripts, and the defense policy
src/ref/, src/render/	The PIN referee, and the three.js view
src/main.ts, src/review.ts, src/setup.ts	The simulator page, the review mode, and the robot setups
index.html, sim/index.html	The home page and the simulator page. Both are Vite entries.
public/	The field and ball models, and the built Match Lab and lessons pages
scripts/	Headless runners, the experiment tools, the model converters, and the site builder
experiments/	Results and logs of every measured change
traces/	Annotated matches that drove the planner fixes
functions/, db/, wrangler.toml	The match counter on Cloudflare Pages and D1
.github/workflows/ci.yml	The checks that every pull request must pass
docs/	The lessons, the simulator description, the HIVE calibration, and the backlog

The site

npm run build produces the whole static site in dist/. The Match Lab and the lessons page are generated by python3 scripts/build-site.py and committed under public/, so the build needs no Python. Run that script after you change docs/top-ten.md, the template, or the result files.

The home page shows a live count of simulated matches and of the countries that they came from. functions/api/matches.js is a Cloudflare Pages Function that keeps the counts in a D1 database, because D1 increments atomically. It stores a visitor's address only as a salted hash, for one day, and a country only as a count per two-letter code.

Deployment

Cloudflare Pages deploys the site by its Git integration: a merge to main deploys to production, and every pull request gets a preview URL. Branch protection requires the Build and test check, so a change that fails its tests can't reach main. The Pages project uses the build command npm run build and the output directory dist. .node-version pins Node.js 22, and wrangler.toml supplies the D1 binding. A preview gets no database binding, so a preview can't change the real count.

To deploy your own copy, follow these steps:

1. To create the database, run wrangler d1 create DB_NAME, and put the ID that it prints in wrangler.toml.
2. To create the tables, run wrangler d1 execute DB_NAME --remote --file db/schema.sql.
3. In the Cloudflare dashboard, go to Workers & Pages, create a Pages project from your fork, and set the build command and the output directory as described earlier.

Sources

• Field geometry. The official field CAD from the FIRST Playing Field Resources page. scripts/convert-step.mjs converts the STEP file to public/field.glb and writes cad/field-manifest.json, and scripts/convert-balls.mjs extracts the ball models. The STEP file isn't in the repository.
• Rules and point values. The BIOBUZZ Competition Manual, sections 9 and 10.
• HIVE tipping point. The Event Field Setup Guide, section 12.3.
• Ball masses. AndyMark's product page: 0.055 lb for POLLEN (am-5851) and 0.091 lb for NECTAR (am-5852). The manual's section 9.8 names the material, polyethylene, and gives no weight. node scripts/ball-mass.mjs checks the weights against the plastic volume of the CAD models.

Contribute

See CONTRIBUTING.md. The fastest bug report is an annotated match: review a match in the simulator, click the robot that did something wrong, type a note, click Export, and attach the files to an issue.

License

MIT for the code, the documents, and the experiment data. The field and ball models and the trademarks belong to others: see NOTICE.md.