Game Components Library

A modular Cairo smart contract library for building on-chain games on Starknet. Provides reusable components for managing game state, player tokens, and tournament/event systems with comprehensive testing and deployment tools.

Architecture

Component Relationships

Metagame
  ├── minigame_token_address ──→ MinigameToken (ERC721)
  ├── context_address ──→ IMetagameContext (optional)
  └── IMetagameCallback ◀── update_game() dispatches callbacks

MinigameToken
  ├── game_address ──→ Minigame
  ├── registry_address ──→ Registry (multi-game mode)
  └── token_metadata
      ├── settings_id ──→ IMinigameSettings
      └── objectives ──→ IMinigameObjectives

Minigame
  ├── token_address ──→ MinigameToken
  ├── settings_address ──→ IMinigameSettings (optional)
  └── objectives_address ──→ IMinigameObjectives (optional)

Game Lifecycle

1. Setup: Deploy contracts with extension addresses configured
2. Mint: Create tokens with game configuration and metadata
3. Play: Validate is_playable() and update game state through minigame logic
4. Sync: Call update_game() to synchronize token state with game results. If the minter implements IMetagameCallback, callbacks are dispatched automatically (on_game_action, on_game_over, on_objective_complete)
5. Complete: Game ends when game_over() returns true or all objectives achieved

Packages

Embeddable Game Standard

Core components for onboarding games onto Starknet.

Module	Description	Docs
token	ERC721 NFT representing playable game instances with compile-time feature flags (<4MB optimization)	README
minigame	Individual game logic foundation requiring IMinigameTokenData implementation	README
metagame	High-level game management, token delegation, and context coordination	README
registry	Game registration, discovery, and metadata management	README

Metagame

Components for applications that coordinate and interact with games.

Module	Description	Docs
leaderboard	Tournament scoring, ranking, and multi-tournament support	README
registration	Player registration tracking for tournaments, quests, and other contexts	README
entry_requirement	Entry gating via token ownership, allowlists, or external validators	README
entry_fee	Entry fee management with ERC20 deposits and share distribution	README
prize	Prize management for ERC20/ERC721 rewards with claim tracking	README
ticket_booth	Payment-enabled game access with tickets and golden passes	—

Game Economy

Module	Description	Docs
tokenomics	Ekubo TWAMM buyback and stream token distribution	README

Utilities

Module	Description	Docs
math	Fixed-point math library (32.32 bit) based on Cubit	README
distribution	Share computation with Linear, Exponential, Uniform, and Custom distributions	README
utils	Encoding, JSON generation, and token metadata rendering	README
renderer	SVG/HTML rendering and font embedding for token metadata	—

Presets

Package	Description	Docs
presets	Ready-to-deploy contracts (LeaderboardPreset, AutonomousBuyback, StreamToken)	README

Cross-Cutting

Package	Description	Docs
interfaces	Centralized interface and struct definitions shared across all components	README

Testing Infrastructure

Package	Description
testing	Shared test constants and addresses
test_common	Shared mock contracts and example implementations

Quick Start

Prerequisites

• Scarb: 2.20.1
• Starknet Foundry: 0.63.0

Installation

# Clone the repository
git clone <repository-url>
cd game-components

# Build the entire workspace
scarb build

# Run tests for a specific module
snforge test --filter token

# Run tests with coverage
snforge test --filter token --coverage

Basic Usage

// Deploy a simple game token
use game_components_embeddable_game_standard::token::core::CoreTokenComponent;
use game_components_interfaces::minigame::{IMinigame, IMinigameTokenData};

#[starknet::contract]
mod MyGameToken {
    use super::CoreTokenComponent;

    component!(path: CoreTokenComponent, storage: core_token, event: CoreTokenEvent);

    #[abi(embed_v0)]
    impl CoreTokenImpl = CoreTokenComponent::CoreTokenImpl<ContractState>;
}

Extension System

Game Components uses interface-based extensions for modularity:

Extension	Purpose
Enumerable Lite	Optional owner token discovery through RPC
Settings	Game configuration (difficulty, modes, custom parameters)
Objectives	Achievements and goals tracking with completion rewards
Context	Tournament/event metadata and cross-game coordination
Callback	Automatic metagame notifications on score/game_over/objective events
Minter	Custom minting logic and access control
Renderer	Dynamic UI/metadata generation for tokens
Soulbound	Non-transferable tokens for achievements
Skills	Per-token skills address overrides with batch operations
Multi-game	Support multiple games in one token collection

Implementation Pattern

// Check for extension availability
if src5_component.supports_interface(IMINIGAME_SETTINGS_ID) {
    let settings = IMinigameSettingsDispatcher { contract_address: settings_address };
    // Use extension functionality
}

Development Workflow

Build Commands

# Build entire workspace
scarb build

# Format code
scarb fmt -w

Testing Commands

# Run all tests for a module
snforge test --filter token

# Run with coverage
snforge test --filter token --coverage

# Run a specific test by name
snforge test --filter test_mint_basic

# Run with custom fuzzer iterations
snforge test --filter token --fuzzer-runs 256

Deployment Scripts

# Deploy mock contracts for testing
./scripts/deploy_mocks.sh

# Deploy optimized token contract
./scripts/deploy_optimized_token.sh

# Deploy StreamToken factory
./scripts/deploy_stream_token_factory.sh

# Create game settings
./scripts/create_settings.sh

# Create game objectives
./scripts/create_objectives.sh

# Create stream token
./scripts/create_stream_token.sh

# Mint game tokens
./scripts/mint_games.sh

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Built with love for the Starknet gaming ecosystem by Provable Games

Pinned coverage tooling

Scarb 2.20.1 bundles Cairo 2.20.0. CI builds cairo-coverage 0.6.0 with our pinned Cairo 2.20 compatibility adapter instead of downloading a moving installer. Run scripts/setup_coverage.sh and add $PWD/.validation-tools/bin to PATH before running snforge test --coverage. The adapter revision, patch and locked Rust dependency graph live in tools/coverage/; its build requires Rust 1.96.0 and network access initially. The existing development profile retains the debug information and disabled inlining required for coverage. Benchmark comparisons must use identical profiles.

Felt-storage ERC721

The ERC721 package provides a maintained OpenZeppelin 4.0.1 component with checked felt token-key and balance storage, standard u256 public interfaces, and complete ERC721/royalty regression coverage. It can be imported directly as game_components_erc721 from a reviewed repository commit. Its README records the storage layout, supported domain, and upstream provenance.

The dependency-free encoding package exports canonical RFC 4648 Base64 for ByteArray. Its separate test harness carries the full 401-test validation corpus without adding dependencies to the production library.