A thrilling Web3 racing game built on the Sui blockchain where players can mint, customize, and race their unique Duck NFTs in real-time animated races!
- Multiplayer Racing: Race ducks from multiple Sui addresses simultaneously
- 30-Second Races: Fast-paced, exciting races with animated SVG ducks
- Real-Time Animation: Smooth racing animations powered by Framer Motion
- Prize System: Send SUI rewards to race winners directly on-chain
- Unique Duck NFTs: Each duck is a fully customizable NFT on Sui blockchain
- Color Customization: Choose from 6+ body colors and beak colors
- Accessories: Crown, bowtie, sunglasses, or none
- Patterns: Spots, stripes, or clean designs
- Procedural Generation: Default ducks generated for addresses without NFTs
- Dynamic Fields: Efficient component storage using Sui's dynamic field system
- Pack/Unpack States: Edit mode (unpacked) and complete NFT mode (packed)
- Event System: Comprehensive events for all NFT operations
- Gas Efficient: Optimized for low transaction costs
- On-Chain SVG Generation: Duck images stored as base64 SVG data
- Metadata Rich: Complete NFT metadata with traits and attributes
- Transferable: Full ownership transfer capabilities
- Composable: Mix and match components for unique combinations
- Next.js 15 with Turbopack for fast development
- TypeScript for type safety
- Tailwind CSS 4.1 for styling
- Framer Motion for animations
- Sui dApp Kit for blockchain integration
- Sui Move 2024 smart contract
- Dynamic Fields for flexible component storage
- Event-driven architecture for frontend integration
- Gas-optimized operations
// Create a new customizable duck
create_duck(name: String, body_color: String, beak_color: String): DuckNFT
// Customize components (unpacked state only)
customize(duck: &mut DuckNFT, body_color?, beak_color?, accessory?, pattern?)
// Pack into complete NFT with metadata
mint(duck: &mut DuckNFT, image_url: String, metadata: String)
// Edit existing duck (alias for customize)
edit(duck: &mut DuckNFT, body_color?, beak_color?, accessory?, pattern?)
// Transfer ownership
transfer_duck(duck: DuckNFT, recipient: address)- Body Colors:
#F4D03F(Classic Yellow),#4A90E2(Ocean Blue),#FF8C42(Sunset Orange),#7FD8BE(Mint Green),#B19CD9(Lavender),#FF6B9D(Hot Pink) - Beak Colors: Any hex color matching your style
- Accessories:
crown,bowtie,sunglasses,none - Patterns:
spots,stripes,none
- Node.js 18+ and npm/yarn/pnpm
- Sui Wallet (Suiet, Ethos, or Sui Wallet)
- Testnet SUI (get from Sui Faucet)
- Clone the repository
git clone <repository-url>
cd duck-race-onchain2.Install dependencies
npm install
# or
yarn install
# or
pnpm install3.Configure environment
cp .env.example .env.localAdd your Sui configuration:
NEXT_PUBLIC_DUCK_NFT_PACKAGE_ID=0x9c4573ac14e52838f5d477aaa05791d5bee6a23de1830832c48a41f1e72a2c4d
NEXT_PUBLIC_NETWORK=testnet4.Start development server
npm run dev
# or
yarn dev
# or
pnpm dev5.Open http://localhost:3000
- Click "Connect Wallet" and select your Sui wallet
- Ensure you're on Sui Testnet
- Enter Sui addresses in the participant fields
- Each address can bring their Duck NFTs to race
- Minimum 2 participants required
- Create new ducks with
create_duck - Customize colors, accessories, and patterns
- Mint your duck to make it race-ready
- Click "Start Race!" to begin the 30-second race
- Watch your ducks compete in real-time animation
- See results and send SUI prizes to winners
- Use the built-in SUI transfer feature to reward winners
- All transactions happen on-chain with full transparency
- Randomized Paths: Each duck follows a unique animated path
- Speed Variation: Different speeds based on duck customization
- Collision Detection: Smooth racing without overlap issues
- Finish Line Logic: Precise timing determines race positions
- Winner Selection: Automatic winner determination
- SUI Rewards: Send SUI directly to winners' addresses
- Transaction History: All transfers recorded on-chain
├── app/ # Next.js app router
│ ├── race/ # Main racing interface
│ ├── duck/ # Duck management
│ └── ducks/ # Duck collection view
├── components/ # React components
│ ├── RaceAnimation.tsx # Core racing animation
│ ├── RaceParticipants.tsx # Address input management
│ ├── RaceControls.tsx # Start/stop race controls
│ └── RaceResults.tsx # Results and prize system
├── hooks/ # Custom React hooks
│ └── useDucksFromAddresses.ts # NFT fetching logic
├── lib/ # Utilities and configuration
│ ├── duck-utils.ts # SVG generation and metadata
│ └── config.ts # Sui network configuration
└── smart_contracts/ # Move smart contracts
├── sources/
│ └── duck_race_nft.move # Main NFT contract
└── DEPLOYMENT.md # Deployment information- Sui Blockchain: High-performance blockchain for NFTs
- Next.js 15: Modern React framework with app router
- Sui dApp Kit: Official Sui blockchain integration
- Framer Motion: Smooth animations and transitions
- Tailwind CSS: Utility-first styling
- TypeScript: Type-safe development
- Package ID:
0x9c4573ac14e52838f5d477aaa05791d5bee6a23de1830832c48a41f1e72a2c4d - Network: Sui Testnet
- Explorer: SuiVision
# Build for production
bun run build
# Start production server
bun start- Mix and match 6+ body colors with any beak color
- 4 accessory options + 3 pattern types = 1000+ combinations
- Each combination is mathematically unique
- Duck images stored as base64 SVG directly on-chain
- No external dependencies for image rendering
- Gas-efficient storage using Sui's object system
- Components stored as dynamic fields for flexibility
- Easy to add new customization options
- Gas-efficient updates and modifications
- Unpacked: Edit mode for customization
- Packed: Complete NFT with metadata and image
- Seamless transition between states
- All NFT operations emit events
- Frontend can react to on-chain changes in real-time
- Complete audit trail of all modifications
{
name: "Speedy Gonzales",
bodyColor: "#F4D03F", // Classic Yellow
beakColor: "#FFD700", // Gold beak
accessory: "crown", // Royal crown
pattern: "stripes" // Racing stripes
}{
name: "Deep Blue",
bodyColor: "#4A90E2", // Ocean Blue
beakColor: "#FF6B35", // Orange beak
accessory: "sunglasses", // Cool shades
pattern: "spots" // Dalmatian spots
}- Parallel Processing: Fast transaction confirmation
- Low Fees: Sub-cent transaction costs
- Scalability: Can handle thousands of NFT operations
- Developer-Friendly: Rich Move language for smart contracts
- True Ownership: Players own their duck NFTs
- Interoperable: Ducks can be used across different games
- Market Value: Unique ducks can have collectible value
- Community: Social features around duck racing
- Sui Documentation - Learn about Sui blockchain
- Next.js Docs - Frontend framework documentation
- Move Language Guide - Smart contract language
- Sui dApp Kit - Blockchain integration
Contributions welcome! Please feel free to submit issues and enhancement requests.
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
MIT License - see LICENSE file for details
- Sui Foundation for the amazing blockchain platform
- Mysten Labs for Sui dApp Kit and tooling
- Next.js Team for the fantastic framework
- Open Source Community for inspiration and contributions
Ready to race? 🏁 Enter addresses, customize your ducks, and experience the thrill of blockchain-powered racing!