Flunks

Project Description

Semester Zero: Finding Flunko is a blockchain-powered interactive mystery adventure built on Flow blockchain. Players navigate a 1990s high school world where their classmate Flunko has mysteriously disappeared. The game combines exploration, social interaction, time-based mechanics, mini-games, and an on-chain NFT reward system.

Players explore iconic locations, collecting GUM points (the in-game currency) through various activities. The world operates on a real-time day/night cycle based on each player's local timezone, with different locations and events accessible at specific times.

Every action has consequences: daily login streaks reward consistency, location-based challenges unlock special content, and completing chapter objectives earns you NFTs. Players can customize their experience with profile pictures, participate in time-limited events and unlock hidden Easter eggs scattered throughout the game world.

Key highlights:

• Chapter-Based NFT Rewards: Complete objectives to earn on-chain NFT's (Slacker & Overachiever achievements)

• Time-Based World Dynamics: Real-time day/night cycles synchronized to each player's timezone, with location access that changes throughout the day

• Interactive Mini-Games: Flappy Flunk arcade game, Flunky Uppy arcade game

• Blockchain-Backed Economy: GUM rewards system with Flow wallet integration, on-chain NFT collections, and achievement tracking

• Social Mystery Narrative: Interactive story driven by player choices, special events and community engagement

• Retro 90s Aesthetic: Authentic period-accurate design with MySpace-style profiles, Windows 95 UI elements, and nostalgic pixel fonts

• Multi-Platform Access: Fully responsive design for desktop and mobile with Dynamic Labs wallet support for seamless Web3 authentication

Semester Zero demonstrates how Web3 mechanics can enhance narrative-driven social gameplay, creating a persistent world where time, choice, community, and verifiable on-chain achievements all matter.

How it's Made

We built Semester Zero: Finding Flunko using Next.js 14 with TypeScript for a robust, type-safe foundation. The frontend leverages React components with Tailwind CSS for responsive, retro-styled UI elements that authentically capture the 1990s aesthetic, including custom Windows 95 pixel fonts (ms_sans_serif) for that nostalgic feel.

Time-based mechanics are handled client-side with timezone-aware utilities that synchronize day/night cycles and location access across all users based on their individual local time zones — no two players see the same world at the same time unless they share a timezone.

Blockchain & Wallet Integration

On the blockchain side, we integrated Flow via Dynamic Labs SDK v4 for seamless wallet authentication, supporting Flow Wallet, Lilico, Blocto, and Dapper. We built a custom SemesterZero smart contract (deployed at 0x807c3d470888cc48) that manages:

• Chapter 5 NFT Collection: Players enable their collection through the Paradise Motel lobby, creating an on-chain NFT receiver capability

• Achievement Tracking: Slacker (night-time Paradise Motel Room 7 visits) and Overachiever (Hidden Riff challenge completion) objectives tracked on-chain

• NFT Airdrops: Automated admin functions to airdrop Chapter 5 completion NFTs when both objectives are met

• GumDrop System: Time-limited reward windows (72-hour Halloween events) managed via smart contract

Backend Architecture

The GUM reward system uses Supabase as the backend database, tracking user transactions, cooldowns, achievement progress, and event participation (homecoming dance, picture day voting) with PostgreSQL triggers and row-level security policies. We built custom Next.js API routes to manage complex logic for:

• Daily login rewards with streak tracking

• Time-gated activities (night-only room access, scheduled events)

• Anti-abuse cooldown systems (30-second to 24-hour cooldowns depending on activity)

• Blockchain registration of achievements via admin authorization

• Picture day voting system with wallet-based authentication

• Homecoming dance attendance tracking for Chapter 4 Slacker rewards

Advanced Features

The time-based access system uses a sophisticated hook architecture (useTimeBasedAccess) that checks real-time conditions against configurable rules stored in the database. This allows for dynamic scheduling of events, location availability, and special rewards without requiring code deployments.

Mini-games are built as standalone React components with their own game loops, physics engines (Flappy Flunk uses canvas-based collision detection), and reward systems integrated with the main GUM economy.

Tech Stack:

• Frontend: Next.js 14, React, TypeScript, Tailwind CSS, custom Windows 95 fonts

• Blockchain: Flow blockchain (Mainnet 0x807c3d470888cc48), Dynamic Labs SDK v4 (Flow wallet connectors), custom Cadence smart contracts

• Backend: Supabase (PostgreSQL with RLS), Next.js API Routes, server-side validation

• Deployment: Vercel for frontend hosting with environment-specific builds, automatic cache invalidation for network switching

• Time Management: Timezone-aware utilities (per-user day/night cycles), server-side validation, database-driven schedules

• Authentication: Dynamic Labs with Flow wallet integration, wallet-based user sessions, FCL configuration with automatic testnet cache clearing

Hackathon Challenges Overcome

We encountered and solved several interesting challenges:

1. Network Switching Bug: FCL was caching testnet configuration in browser localStorage even when code specified mainnet. We implemented automatic cache detection and clearing on app initialization.

2. Mobile Wallet Support: Getting WalletConnect to work properly on mobile required understanding the Flow React SDK documentation and properly configuring the walletconnect.projectId and flow.network parameters.

3. Timezone Synchronization: Making day/night cycles work per-user required storing timezone offsets and calculating local time server-side to prevent client manipulation while maintaining accurate time-based access control.

4. NFT Collection Setup: Simplifying the user experience for enabling NFT collections required careful UX design — we made it a single-click process in the Paradise Motel lobby with clear success feedback.

The architecture emphasizes modularity — time-based image utilities, GUM transaction services, access control hooks, and mini-game components can all be composed together to create complex game mechanics while maintaining clean separation of concerns.