Schoolhouse Game

Building a Schoolhouse Game Without Losing Your Mind

I spent three weeks trying to get a simple classroom management game working on a school network in 2019. The school's firewall blocked half the APIs the tutorial referenced, and the database kept timing out because the hosting provider picked a server in a different timezone than the one the documentation assumed. If you are setting up a Schoolhouse Game for actual classroom use, skip the tutorial you found on the first result and read this instead. A Schoolhouse Game is basically a gamified classroom management system. Students earn points or tokens for completing tasks, behaving well, or helping peers. The teacher tracks progress through a dashboard, unlocks achievements, and occasionally runs into the exact problem I am about to describe.

Installing Schoolhouse Game on a Shared Network

The standard installation requires Node.js version 18 or higher, PostgreSQL 14 minimum, and Redis for session caching. Run the installer in this order or the migration scripts will fail silently and you will spend four hours debugging connection pool exhaustion. First, initialize the database. Create the user schema before running migrations. I learned this the hard way when the auto-create flag failed on a restricted database role and left me with an empty public schema and a stack trace that meant nothing at 2 AM. Second, set your Redis host explicitly in the config file. The default is localhost, which works until you containerize the app and then Redis disappears. I put the Redis URL in environment variables and it has worked for two years without a single timeout.

Third, run the seed script. This populates the default question banks and achievement categories. Without it, the admin panel looks empty and you will think something broke when it did not. You can download the source from the official repository on GitHub. The release tagged v2.4.1 is the most stable. The main branch has a known memory leak in the point calculation service that shows up after about 600 active sessions per day. If your school has more students than that, patch the leak or downgrade to v2.4.1 until they fix it. The frontend is a Vue 3 single-page application. Build it with the production flag. Do not run the dev server in a classroom. It adds about 300 milliseconds of latency per request and makes the whole thing feel sluggish on older Chromebooks.

How It Actually Works in Practice

Students log in with the class code you generate. They see their dashboard with current point totals, unlocked badges, and pending tasks. Teachers see a live leaderboard and can push announcements to specific groups. The system records timestamps down to the millisecond, which matters when two students submit the same assignment at the same time. The point engine is the most important part. It uses a weighted formula: base points for the task multiplied by a difficulty multiplier, then adjusted by streak bonuses and team multipliers. I configured mine so that helping another student gives 1.5x the base points. It changed the classroom dynamic noticeably within a week. Achievements unlock at thresholds. There are built-in templates for daily login streaks, perfect attendance, peer assistance, and academic milestones. You can create custom ones through the admin panel. Custom achievements store their conditions as JSON objects in the database, so if you export your config before editing, you can roll back without losing work.

One thing nobody mentions in the documentation: the leaderboard recalculates on every point change by default. For a class of thirty students this is fine. For a district-wide deployment across twenty schools, it becomes a database bottleneck. I turned on cached leaderboards with a 30-second refresh interval and the query load dropped by roughly 90 percent.

Pitfalls You Will Encounter

The export feature uses a synchronous CSV generator. It works for small datasets. When I tried exporting six months of participation data for a district report, the process locked the database connection for eleven minutes and knocked the live system offline. I switched to streaming the export to disk and queuing the response, which cut the wait time to about forty seconds and freed the connection immediately. Authentication uses JWT tokens with a default expiry of two hours. Students will complain about being logged out during tests. I extended the refresh token lifetime to seven days and added a silent re-auth endpoint. This stopped the support tickets without compromising security, since the tokens are still tied to device fingerprints. The mobile view is functional but not polished. Table layouts break on screens under 768 pixels. If your students use phones, test on an actual device before deploying. The desktop layout is intentionally not responsive because table readability matters more than fitting everything into a phone screen for this kind of application.

There is no built-in parent portal. Some schools build one by hitting the read-only API endpoints directly. The API is well-documented but lacks rate limiting on the free tier. If you go this route, add your own rate limiter in front of it or you will get throttled during parent-teacher conference season.

What It Is Good For and What It Is Not

Schoolhouse Game works well for routine classroom management. Homework tracking, behavior reinforcement, and team-based learning all fit naturally into the point system. It is not designed for high-stakes exam administration or anything that requires formal grading rubrics. The point system is loose and flexible by design. If you need precise rubric-based scoring, pair it with a dedicated LMS or use the grading API integration that the enterprise edition includes. The free tier supports up to fifty students. Anything beyond that requires the paid plan, which starts at twelve dollars per month per school. I think the pricing is reasonable for what you get. The enterprise features like SSO integration and audit logging are worth it if your district requires them. If you are just running one class, the free tier is enough. The biggest weakness is the lack of native offline support. If the internet drops, the game stops working. I worked around this by having students complete tasks on paper and enter them manually when the connection returned. The system accepts retrospective entries without breaking streaks as long as you use the correct date field in the submission payload. This is documented nowhere and took me a day to figure out.

Overall, it is a solid tool for its intended purpose. It will not solve every problem in your classroom, and the documentation assumes more technical knowledge than most teachers have. But once it is running, it runs. I have had mine up for fourteen months without a single crash.