GITZILLA

Your code becomes the combat: GitHub repos turn into heroes, dependency graphs become destructible bosses, and phones control a shared 3D arena with Vision Pro support.

Comment

Inspiration

Bring your repo. Tilt your phone. Survive the merge.

What if you could fight a codebase and understand it better afterward? In GITZILLA:

  • a heavily imported file becomes a monster's heart;
  • a software component becomes a breakable limb;
  • a dependency cycle becomes a weak point you can exploit.

Break a limb and the attack that component powers disappears.

We built GITZILLA at HackPSU to make code tangible through shared play. One thread runs from source analysis to character generation, combat, the 3D tabletop, and the signed result you take home.

What it does

GITZILLA is a browser multiplayer game with three complete modes, switchable 2D and 3D views, phone motion controls, and an Apple Vision Pro tabletop. Everyone joins by scanning a QR code; there's no app to install.

PvP royale: bring your repository into the rivalry

  • The match: two to eight repository-powered fighters, no respawns, and a shrinking "GC sweep" zone. The last player standing wins.
  • Identity and eligibility:
    • each player signs in with GitHub through Auth0, which establishes identity;
    • the server then verifies repository ownership through the GitHub API, and rechecks it when the match starts.
  • Repo Power explains how measured repository signals shape each fighter:
    • 60% code-quality heuristics: testing, modularity, cohesion, documentation, and cycle/debt hygiene;
    • 40% logarithmically scaled reach: stars, contributors, analyzed source size, and commit activity.

The score maps into bounded combat stats. It's an explainable game mechanic, not a universal software-quality grade.

  • Results: placements, KOs, damage, a git-log kill feed, and a royale wins board keep the rivalry going after the match.

Cooperative raids: dismantle the architecture

  • The boss: one to eight players face a boss generated from a rival repository. Its components, import graph and cycles shape its anatomy and weak points.
  • Variety: four boss archetypes, rendered across nine body plans and seven element themes, give each codebase a distinct form.
  • Attacks: each attack belongs to a specific component, so choosing which limb to destroy changes the fight.
  • Heroes: they keep equal stat budgets, separate from PvP's Repo Power.
  • After the raid: an autopsy explains the broken components, and "Adopt an Organ" connects players to the maintainers and open issues behind them.

Classroom raids: code together, improve together

Beginners lose interest quickly, and teachers often can't see who's stuck until it's too late. Classroom mode turns practice into a shared, low-stakes game.

  • Setup:
    • a teacher hosts up to 30 students and publishes ordered tasks with timers, rubrics and evidence checks;
    • nine Python lesson presets (variables, conditions, loops, lists, functions, dictionaries) include starter code, self-checks and teacher guidance;
    • students code in an in-browser Python editor with no setup, or submit a GitHub revision.
  • Task cards: each one shows the goal, the to-dos, "done when" checks that tick ✓/✗ after every submission, the expected output, and staged hints.
  • The class attack: every improvement becomes damage on a shared class boss.
    • Only improvement counts, so an unchanged score can't farm progress, and effort is rewarded rather than prior skill.
    • The boss's health is budgeted across the whole lesson.
  • What teachers see:
    • private review detail;
    • round and lesson debriefs: participation, the hardest checks, what to reteach, who needs help, shout-outs;
    • CSV and Markdown exports.
  • The projector shows class aggregates only, never struggling students' names.
  • Checks:
    • file and literal checks inspect the source without executing student code on the server;
    • CI checks require a successful GitHub check run for the exact submitted commit.

What makes GITZILLA distinctive

Source code becomes an explainable character

  • Analysis:
    • the pipeline inspects bounded repository archives and extracts import relationships across nine languages;
    • Tarjan's strongly connected components algorithm finds cycles;
    • real identifiers, source paths and filtered code excerpts give each character its vocabulary and look.
  • The Genesis reveal shows the transformation from source facts to kit attributes and appearance, reading the actual generated kit.
  • Honest limits: large repositories are sampled within explicit limits, and missing measurements are labelled rather than invented.

Phones become physical controllers

  • Gestures: tilt to move, tap or flick to attack, swipe or tilt hard to dash, and move the phone in a circle (keeping it upright) or hold to use a skill. Movement follows the screen in any orientation on iPhone and iPad.
  • Learning and fallbacks: a training flow teaches each gesture. Touch-only, seated and keyboard-and-mouse modes offer other ways to play.
  • Phone as gamepad: signing in with the same GitHub account links your phone to your seat on a big screen or a Vision Pro. The phone provides the controls and the larger display shows the fight.

The arena becomes a spatial tabletop

  • 3D view: the Three.js/WebGL renderer turns pixel-art heroes and bosses into voxel-extruded sprites with real depth and lighting. The same authoritative match state drives both 2D and 3D, and players switch between them in settings.
  • Vision Pro:
    • in Safari on Apple Vision Pro, WebXR immersive VR puts the live arena on a world-pinned virtual tabletop, with a floating HUD and a linked phone as the controller;
    • on victory, the boss dissolves into voxels, the table turns into a blue screen, and a pinch returns to the autopsy;
    • we played it on a real headset.
  • Limits: Vision Pro Safari offers VR only, with no passthrough. AR tabletop placement is enabled only on runtimes that support it.

Results carry verifiable history on Solana

  • Signed receipts:
    • eligible public PvP matches with at least two human players give each player a downloadable Ed25519-signed match receipt;
    • no wallet is needed to play or to download it.
  • Optional anchoring:
    • the player signs a message in Phantom or Solflare, and GITZILLA sponsors a single Solana devnet Memo transaction carrying the receipt ID and a salted SHA-256 digest;
    • no names, repositories or code go on-chain;
    • players never pay and never sign a transaction.
    • Verified end to end: our first real anchor, from a two-player royale, is finalized on devnet at slot 514,986,981.
  • The "⛓ Verified on Solana" board:
    • adds player and project standings;
    • each snapshot is hashed into a Merkle tree, and its root is anchored in one devnet Memo;
    • every row has a verify button that checks its inclusion proof in the browser against that same on-chain root.
    • Verified live: the board's first populated snapshot is finalized at slot 514,999,427.
    • Player rows are recorded for matches from launch onward.
  • What it proves: receipts and roots make the server's recorded results tamper-evident, since history can't be quietly rewritten after anchoring. They don't independently prove fair gameplay.

How we built it

  • An authoritative multiplayer core.
    • TypeScript contracts connect analysis, simulation, server and clients.
    • Node.js advances combat at 30 Hz and broadcasts WebSocket snapshots at 20 Hz.
    • The server validates input, acknowledges sequences, releases stale controls after 300 ms, and arbitrates linked phone/display input.
    • Reconnects restore the latest state without replaying old combat events.
    • Clients play back on an adaptive clock that absorbs network jitter.
  • Gemini character direction grounded in source code.
    • For public repositories, Gemini receives bounded structure, README context and extracted identifiers. It returns schema-constrained designs, names and taunts, which local code validates and renders.
    • Gemini never sets combat stats or drives the boss AI.
    • Deterministic appearances make characters available immediately, and Gemini, cached or DeepSeek results refine them in the background.
    • Credentialed analyses skip external art generation.
  • Hosted on Vultr.
    • The live game server, the WebSocket rooms, the classroom engine and the receipt/leaderboard storage (SQLite) all run on our Vultr instance as a dedicated, sandboxed service.
    • Deploys use immutable Git revisions, configuration checks, state backups, a fresh-process health check, and automatic rollback.
    • Pending Solana transactions are saved before broadcast, so retries and restarts reuse the exact signed bytes.
  • A cohesive browser stack.
    • Vite builds the client; Canvas and Three.js render the game; WebAudio plays the chiptune soundtrack.
    • The interface and lessons support English, Simplified Chinese, Spanish and French.
    • Our workflow used Cursor, Grok Bot, Claude Code and Codex, with Vitest and Playwright for verification.
  • We used Cursor to plan how repository components become boss limbs, define boss movement and attack patterns, and specify the Genesis cinematic’s TypeScript interfaces, while Grok Bot supported the build as an additional AI coding assistant.

Challenges we ran into

  • Consistency. One repository has to stay consistent across analysis, stats, generated art, the Genesis explanation and two renderers. We separated those responsibilities and kept the simulation authoritative.
  • Phone input. Mobile input needed more than a permission grant:
    • the app waits for real sensor readings and maps tilt to the screen in every orientation;
    • it handles lost streams and keeps a linked display's idle traffic from overriding the phone;
    • we tuned the gestures using motion traces recorded on real phones.
  • Rendering. We fixed resource cleanup across rematches and removed full-screen flashes for photosensitive players. We also tuned the Vision Pro table height and HUD after testing on the headset.
  • Upstream failures. Bounded analysis, credential-scoped caches, pre-analyzed examples and model fallbacks keep raids and practice working when upstream services fail. PvP still performs live identity and eligibility checks, and receipt downloads work even when anchoring is unavailable.

Accomplishments we're proud of

Our hackathon feature scope is complete and live. It covers three playable modes, explainable character creation, 2D and 3D, Vision Pro, phone controllers, teacher workflows, and signed results anchored on Solana devnet.

Production foundations:

  • reconnect and restart recovery;
  • host moderation and ownership transfer;
  • private student feedback;
  • bounded input and archive processing;
  • persistent result storage;
  • health-checked deploys with rollback.

The repository records repeated multiplayer test runs, browser checks, controller regressions built from real-device traces, and receipt tampering and replay tests. These are concrete engineering milestones, not a claim of unlimited scale or universal device support.

What we learned

An engaging technical product lets people see cause and effect:

  • a dependency cycle becomes a weak point;
  • a measured repository signal becomes a visible stat;
  • a finished match becomes a signed, verifiable result.

Each layer gives the player another way to understand the code and the system behind the game.

What's next

Our next step is operational validation:

  • longer load tests;
  • more physical devices;
  • a rehearsed backup restore;
  • pilots in real classrooms, to learn whether shared play helps beginners stay engaged.

Try it

Hackathon entries: HackPSU main competition, General Track: The Mystery Stack, Nittany AI Challenge, MLH Best Use of Gemini API, Auth0, Vultr, Solana, DEV Writing, and the SpaceXSI A-Team raffle. Our Mystery Stack demonstration shows at least four real people using phone motion controls in the same royale.

Built With

Share this project:

Updates

Submission history