Skip to main content

Quick Start: Rendering Preon NFTs

Immediate Integration (5 minutes)

1. Add to Any Page

2. View Another User’s Preon

3. Show Traits Data

Adding 3D Models (Optional)

Step 1: Get/Create Models

Free Resources: Create in Blender:
  1. Model your species (Wolf/Owl/Shark)
  2. File → Export → glTF 2.0 (.glb)
  3. Enable “Apply Modifiers” and “Compression”

Step 2: Add to Project

Step 3: Optimize (Optional)

Step 4: Test

The PreonModel component will automatically:
  • Load the correct model based on species trait
  • Fall back to geometric shapes if model not found
  • Apply dynamic materials based on traits

Advanced: Custom Rendering

Method 1: Static Image Badge

Method 2: Canvas 2D Dynamic

Method 3: SVG Dynamic Badge

Minting New Preons

Programmatically (Advanced)

Display Options Comparison

Option 1: Full 3D Viewer (Current)

Best for: Main profile page, showcase
Pros: Immersive, interactive, impressive Cons: Heavy, slower on mobile

Option 2: 2D Canvas

Best for: Leaderboards, lists, compact views
Pros: Fast, lightweight, customizable Cons: Less impressive, no 3D depth

Option 3: Static Badge

Best for: Inline mentions, compact UI, mobile
Pros: Instant load, minimal resources Cons: Not interactive, less detail

Testing Checklist

  • Preon exists on-chain (check with audit_preon_addresses.py)
  • User has smart wallet address in Firestore
  • usePreon hook returns hasPreon: true
  • Traits are populated (not null)
  • 3D canvas renders without errors
  • Loading states work correctly
  • Error boundaries catch missing models
  • Mobile performance is acceptable
  • Colors match trait values (trustHue)
  • Species shape matches trait (Wolf=1, Owl=2, Shark=3)

Troubleshooting

”No Preon found”

Check:
  1. Run audit: cd cortex && python3 audit_preon_addresses.py
  2. Verify user has smartWalletAddress in Firestore
  3. Run oracle: python3 -m run_oracle --all-users --force-mint

3D viewer is black/empty

Check:
  1. Browser console for errors
  2. Model file exists in public/models/species/{species}.glb
  3. Try different species (should fall back to geometry)
  4. Check browser WebGL support

Traits show “Not available”

Fix:
  1. Ensure using correct address (smart wallet, not EOA)
  2. Check contract on BaseScan: https://sepolia.basescan.org/address/0xaa967c233102c4e16c3891e77d6e3c8ceedc1020
  3. Verify traits were updated after minting

Performance issues

Optimize:
  1. Use lazy loading: dynamic(() => import('./PreonCanvas'), { ssr: false })
  2. Reduce particle count in PreonCanvas
  3. Implement viewport visibility detection
  4. Use smaller 3D models (< 2MB)

Next Steps

  1. Add real 3D models - See “Adding 3D Models” section
  2. Implement metadata API - For OpenSea compatibility
  3. Create showcase gallery - Display all Preons
  4. Add evolution animations - Trait updates with transitions
  5. Build comparison tool - Compare two Preons side-by-side
For complete details, see PREON_NFT_RENDERING_GUIDE.md