sui-game-sdk 0.0.1

package/README.md

@@ -0,0 +1,163 @@
+# SUI Game SDK
+
+The ultimate SDK for building games on SUI. Includes Session Keys, Asset Spawning, and Game State Synchronization.
+
+## Features
+
+### 1. Session Manager
+Eliminate wallet popups during gameplay.
+- Generate ephemeral Ed25519 keys locally
+- Export/Import session state
+- Sign transactions seamlessly
+
+### 2. Asset Spawner
+Simplified API for minting game objects using Move calls.
+- Fluent `spawn(recipient, attributes)` API
+- Auto-formats vector arguments for attributes
+
+### 3. Game State Sync
+React to on-chain game events in real-time.
+- Poll for specific Move events
+- Subscription-based handler pattern
+
+## Installation
+
+```bash
+npm install sui-game-sdk
+```
+
+## Quick Start
+
+```typescript
+import { SessionManager, AssetSpawner, GameStateSync } from 'sui-game-sdk';
+import { SuiClient } from '@mysten/sui/client';
+
+const client = new SuiClient({ url: 'https://fullnode.testnet.sui.io' });
+
+// 1. Create Session
+const session = new SessionManager(client);
+console.log('Session Address:', session.sessionAddress);
+
+// 2. Spawn Asset
+const spawner = new AssetSpawner(client, {
+    packageId: '0x...',
+    module: 'hero',
+    function: 'mint_hero',
+    adminCapId: '0x...'
+});
+
+// 3. Listen to Events
+const sync = new GameStateSync(client);
+sync.subscribe('0x...::hero::LevelUpEvent', (event) => {
+    console.log('Level Up!', event.parsedJson);
+});
+sync.startPolling('0x...');
+```
+
+## Starter Templates
+
+Kickstart your game development with our ready-to-use starter templates:
+
+### Generate a Starter
+
+```bash
+npx sui-game-sdk init
+```
+
+You'll be prompted to choose from:
+
+#### 1. **TypeScript (Web/Node)**
+Full-featured starter with all SDK components. Perfect for web games or backend services.
+- Uses SessionManager, AssetSpawner, GameStateSync
+- Includes sample "Sui Quest" game
+- Move contract included
+
+#### 2. **Next.js (Web App)**
+Modern React web application with beautiful UI.
+- Direct SDK integration
+- Real-time event streaming
+- Tailwind CSS + glassmorphic design
+- Production-ready structure
+
+#### 3. **Unity (C# Scripts)**
+Game engine integration for Unity developers.
+- Simulates SDK patterns in C#
+- HTTP/RPC blockchain communication
+- Organized Assets folder structure
+- Compatible with Unity 2021.3+
+
+#### 4. **Godot (GDScript)**
+Game engine integration for Godot developers.
+- Simulates SDK patterns in GDScript
+- HTTP/RPC blockchain communication
+- Standard Godot 4 project structure
+- Signals for event handling
+
+### Starter Features
+
+All starters include:
+- ✅ Sample "Sui Quest" game (Mint Hero, Slay Boar, Level Up)
+- ✅ Move smart contract (`hero.move`)
+- ✅ Deployment scripts
+- ✅ Comprehensive README
+- ✅ SDK integration examples
+
+### How Starters Use the SDK
+
+- **TypeScript & Next.js**: Direct SDK imports (`import { SessionManager } from 'sui-game-sdk'`)
+- **Unity & Godot**: Simulate SDK concepts using native languages (C#/GDScript)
+
+For detailed SDK usage comparison, see [SDK_USAGE.md](./SDK_USAGE.md)
+
+## Documentation
+
+- [SDK Usage Guide](./SDK_USAGE.md) - How each starter uses the SDK
+- [TypeScript Starter](./starter/README.md)
+- [Next.js Starter](./starters/nextjs/README.md)
+- [Unity Starter](./starters/unity/README.md)
+- [Godot Starter](./starters/godot/README.md)
+
+## Example: Building a Simple RPG
+
+```typescript
+import { SessionManager, GameStateSync } from 'sui-game-sdk';
+import { Transaction } from '@mysten/sui/transactions';
+
+// Setup
+const client = new SuiClient({ url: 'https://fullnode.testnet.sui.io' });
+const session = new SessionManager(client);
+
+// Execute game action
+const tx = new Transaction();
+tx.moveCall({
+    target: `${PACKAGE_ID}::hero::slay_boar`,
+    arguments: [tx.object(heroId)]
+});
+
+const result = await session.executeSessionTx(tx);
+console.log('Action completed:', result.digest);
+
+// Listen for results
+const sync = new GameStateSync(client);
+sync.subscribe(`${PACKAGE_ID}::hero::AttackEvent`, (event) => {
+    console.log('Damage dealt:', event.parsedJson.damage_dealt);
+});
+sync.startPolling(PACKAGE_ID);
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm test
+```
+
+## License
+
+MIT

package/dist/bin/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/cli.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const prompts_1 = __importDefault(require("prompts"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const program = new commander_1.Command();
+program
+    .name('sui-game-sdk')
+    .description('CLI to scaffold Sui Game projects')
+    .version('0.0.1');
+program
+    .command('init')
+    .description('Initialize a new game project')
+    .action(async () => {
+    const response = await (0, prompts_1.default)([
+        {
+            type: 'text',
+            name: 'projectName',
+            message: 'What is the name of your project?',
+            initial: 'my-sui-game'
+        },
+        {
+            type: 'select',
+            name: 'template',
+            message: 'Which starter template would you like?',
+            choices: [
+                { title: 'TypeScript (Web/Node)', value: 'starter' },
+                { title: 'Next.js (Web App)', value: 'nextjs' },
+                { title: 'Unity (C# Scripts)', value: 'unity' },
+                { title: 'Godot (GDScript)', value: 'godot' }
+            ]
+        }
+    ]);
+    if (!response.template || !response.projectName)
+        return;
+    const targetDir = path_1.default.join(process.cwd(), response.projectName);
+    const templateDir = path_1.default.resolve(__dirname, '../starters', response.template === 'starter' ? '../starter' : response.template); // Fix path logic based on structure
+    // In installed package: dist/bin/cli.js -> __dirname is dist/bin
+    // We need to go up two levels to find 'starter' and 'starters' at root
+    let sourcePath = '';
+    if (response.template === 'starter') {
+        sourcePath = path_1.default.resolve(__dirname, '../../starter');
+    }
+    else {
+        sourcePath = path_1.default.resolve(__dirname, '../../starters', response.template);
+    }
+    if (fs_extra_1.default.existsSync(targetDir)) {
+        console.error(`Error: Directory ${targetDir} already exists.`);
+        process.exit(1);
+    }
+    console.log(`\nCreating project in ${targetDir}...`);
+    try {
+        await fs_extra_1.default.copy(sourcePath, targetDir);
+        console.log('\nSuccess! Created project.');
+        console.log(`\ncd ${response.projectName}`);
+        if (response.template === 'starter') {
+            console.log('npm install');
+            console.log('npm run deploy');
+        }
+        else if (response.template === 'nextjs') {
+            console.log('npm install');
+            console.log('cp .env.local.example .env.local');
+            console.log('# Edit .env.local with your package ID');
+            console.log('npm run dev');
+        }
+        else {
+            console.log('Follow the README.md instructions to integrate with your engine.');
+        }
+    }
+    catch (e) {
+        console.error('Error creating project:', e);
+    }
+});
+program.parse();

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './session';
+export * from './spawner';
+export * from './sync';

package/dist/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./session"), exports);
+__exportStar(require("./spawner"), exports);
+__exportStar(require("./sync"), exports);

package/dist/session.d.ts

@@ -0,0 +1,23 @@
+import { SuiClient } from '@mysten/sui/client';
+import { Transaction } from '@mysten/sui/transactions';
+export declare class SessionManager {
+    private ephemeralKeyPair;
+    private client;
+    sessionAddress: string;
+    constructor(client: SuiClient, existingSecretKey?: string);
+    /**
+     * Gets the public key of the session (ephemeral) wallet.
+     * The main wallet should authorize this key to sign transactions on its behalf
+     * (e.g. via Sponsored Transactions or a Smart Account capability).
+     */
+    getPublicKey(): string;
+    /**
+     * Export the session key to save local state (e.g. localStorage).
+     */
+    exportSession(): string;
+    /**
+     * Signs and Executes a transaction using the session key.
+     * Note: This usually requires the transaction to be Sponsored or the Session Key to handle gas.
+     */
+    executeSessionTx(tx: Transaction): Promise<import("@mysten/sui/client").SuiTransactionBlockResponse>;
+}

package/dist/session.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionManager = void 0;
+const ed25519_1 = require("@mysten/sui/keypairs/ed25519");
+class SessionManager {
+    constructor(client, existingSecretKey) {
+        this.client = client;
+        if (existingSecretKey) {
+            this.ephemeralKeyPair = ed25519_1.Ed25519Keypair.fromSecretKey(existingSecretKey);
+        }
+        else {
+            this.ephemeralKeyPair = new ed25519_1.Ed25519Keypair();
+        }
+        this.sessionAddress = this.ephemeralKeyPair.toSuiAddress();
+    }
+    /**
+     * Gets the public key of the session (ephemeral) wallet.
+     * The main wallet should authorize this key to sign transactions on its behalf
+     * (e.g. via Sponsored Transactions or a Smart Account capability).
+     */
+    getPublicKey() {
+        return this.ephemeralKeyPair.getPublicKey().toBase64();
+    }
+    /**
+     * Export the session key to save local state (e.g. localStorage).
+     */
+    exportSession() {
+        return this.ephemeralKeyPair.getSecretKey();
+    }
+    /**
+     * Signs and Executes a transaction using the session key.
+     * Note: This usually requires the transaction to be Sponsored or the Session Key to handle gas.
+     */
+    async executeSessionTx(tx) {
+        tx.setSender(this.sessionAddress);
+        const { bytes, signature } = await tx.sign({ client: this.client, signer: this.ephemeralKeyPair });
+        return this.client.executeTransactionBlock({
+            transactionBlock: bytes,
+            signature: signature,
+            options: {
+                showEffects: true,
+                showEvents: true
+            }
+        });
+    }
+}
+exports.SessionManager = SessionManager;

package/dist/spawner.d.ts

@@ -0,0 +1,19 @@
+import { Transaction } from '@mysten/sui/transactions';
+import { SuiClient } from '@mysten/sui/client';
+export type SpawnConfig = {
+    packageId: string;
+    module: string;
+    function: string;
+    adminCapId: string;
+};
+export declare class AssetSpawner {
+    private client;
+    private config;
+    constructor(client: SuiClient, config: SpawnConfig);
+    /**
+     * Creates a transaction to spawn a new Game Asset (NFT).
+     * @param recipient The player address receiving the asset
+     * @param attributes Optional map of attributes to set immediately (if contract supports it)
+     */
+    spawn(recipient: string, attributes?: Record<string, any>): Transaction;
+}

package/dist/spawner.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AssetSpawner = void 0;
+const transactions_1 = require("@mysten/sui/transactions");
+class AssetSpawner {
+    constructor(client, config) {
+        this.client = client;
+        this.config = config;
+    }
+    /**
+     * Creates a transaction to spawn a new Game Asset (NFT).
+     * @param recipient The player address receiving the asset
+     * @param attributes Optional map of attributes to set immediately (if contract supports it)
+     */
+    spawn(recipient, attributes) {
+        const tx = new transactions_1.Transaction();
+        // This assumes a standard mint function signature:
+        // mint(admin_cap, recipient, attributes_keys, attributes_values)
+        // or similar. This is a generic implementation.
+        const args = [
+            tx.object(this.config.adminCapId),
+            tx.pure.address(recipient)
+        ];
+        if (attributes) {
+            const keys = Object.keys(attributes);
+            const values = Object.values(attributes).map(String);
+            args.push(tx.pure.vector('string', keys));
+            args.push(tx.pure.vector('string', values));
+        }
+        tx.moveCall({
+            target: `${this.config.packageId}::${this.config.module}::${this.config.function}`,
+            arguments: args
+        });
+        return tx;
+    }
+}
+exports.AssetSpawner = AssetSpawner;

package/dist/sync.d.ts

@@ -0,0 +1,20 @@
+import { SuiClient, SuiEvent } from '@mysten/sui/client';
+export type GameEventHandler = (event: SuiEvent) => void;
+export declare class GameStateSync {
+    private client;
+    private pollingInterval;
+    private handlers;
+    private lastTxDigest;
+    constructor(client: SuiClient);
+    /**
+     * Subscribe to a specific Move Event type (e.g. "0x...::game::AttackEvent")
+     */
+    subscribe(eventType: string, handler: GameEventHandler): void;
+    /**
+     * Starts polling for events.
+     * @param packageId The package to filter events by
+     * @param intervalMs Polling interval in milliseconds
+     */
+    startPolling(packageId: string, intervalMs?: number): Promise<void>;
+    stopPolling(): void;
+}

package/dist/sync.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GameStateSync = void 0;
+class GameStateSync {
+    constructor(client) {
+        this.pollingInterval = null;
+        this.handlers = new Map();
+        this.client = client;
+    }
+    /**
+     * Subscribe to a specific Move Event type (e.g. "0x...::game::AttackEvent")
+     */
+    subscribe(eventType, handler) {
+        if (!this.handlers.has(eventType)) {
+            this.handlers.set(eventType, []);
+        }
+        this.handlers.get(eventType)?.push(handler);
+    }
+    /**
+     * Starts polling for events.
+     * @param packageId The package to filter events by
+     * @param intervalMs Polling interval in milliseconds
+     */
+    async startPolling(packageId, intervalMs = 2000) {
+        if (this.pollingInterval)
+            return;
+        this.pollingInterval = setInterval(async () => {
+            try {
+                // Fetch events
+                const events = await this.client.queryEvents({
+                    query: { MoveModule: { package: packageId, module: 'game' } }, // simplified query
+                    limit: 10,
+                    cursor: this.lastTxDigest ? { txDigest: this.lastTxDigest, eventSeq: '0' } : undefined
+                });
+                for (const event of events.data) {
+                    const handlers = this.handlers.get(event.type);
+                    if (handlers) {
+                        handlers.forEach(h => h(event));
+                    }
+                    this.lastTxDigest = event.id.txDigest;
+                }
+            }
+            catch (e) {
+                console.error('Error polling game state:', e);
+            }
+        }, intervalMs);
+    }
+    stopPolling() {
+        if (this.pollingInterval) {
+            clearInterval(this.pollingInterval);
+            this.pollingInterval = null;
+        }
+    }
+}
+exports.GameStateSync = GameStateSync;

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "sui-game-sdk",
+  "version": "0.0.1",
+  "description": "The ultimate SDK for building games on SUI. Session Keys, Spawning, & Sync.",
+  "main": "dist/index.js",
+  "bin": {
+    "sui-game-sdk": "./dist/bin/cli.js"
+  },
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "starter",
+    "starters",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc",
+    "test": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "sui",
+    "game",
+    "sdk",
+    "move",
+    "blockchain",
+    "gaming"
+  ],
+  "author": "dotandev",
+  "license": "MIT",
+  "dependencies": {
+    "@mysten/bcs": "^1.1.0",
+    "@mysten/sui": "^1.21.1",
+    "commander": "^14.0.2",
+    "fs-extra": "^11.3.3",
+    "prompts": "^2.4.2"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^22.10.7",
+    "@types/prompts": "^2.4.9",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.4"
+  }
+}

package/starter/README.md

@@ -0,0 +1,57 @@
+# SUI Game SDK - TypeScript Starter
+
+The reference implementation for the `sui-game-sdk`. This starter project demonstrates the full capabilities of the SDK including Session Management, Asset Spawning, and Game State Synchronization.
+
+## 📦 Features
+- **Session Manager**: Automated session key creation and management.
+- **Asset Spawner**: Streamlined asset creation transactions.
+- **Game State Sync**: Real-time event listening and object syncing.
+- **Sui Quest**: A complete sample game logic (Mint Hero, Slay Boar).
+
+## 🚀 Quick Start
+
+### 1. Install Dependencies
+```bash
+npm install
+```
+
+### 2. Deploy the Game Contract
+This starter requires the `sui_quest` Move package to be published.
+```bash
+# Deploys the contract in 'move/' to Testnet (or localnet if configured)
+npm run deploy
+```
+> **Important**: The deploy script will update `client/index.ts` automatically (or print the ID you need to set).
+
+### 3. Run the Client
+Start the game client simulation:
+```bash
+npm start
+```
+
+## 🎮 How it Works
+
+### Session
+The `SessionManager` creates a temporary wallet for the player.
+```typescript
+const session = new SessionManager(client);
+console.log(session.sessionAddress); // fund this!
+```
+
+### Spawning
+The `AssetSpawner` handles complex Move calls to create assets.
+```typescript
+// (Conceptual usage, check specific implementation)
+spawner.spawn(playerAddress, { ... });
+```
+
+### Syncing
+The `GameStateSync` listens for on-chain events to update the game UI.
+```typescript
+syncer.subscribe('AttackEvent', (event) => {
+    console.log('Damage:', event.damage);
+});
+```
+
+## 📄 License
+MIT

package/starter/client/index.ts

@@ -0,0 +1,79 @@
+import { SuiClient } from '@mysten/sui/client';
+import { SessionManager, AssetSpawner, GameStateSync } from '../../src'; // Import from local SDK
+import { Transaction } from '@mysten/sui/transactions';
+
+// API: Replace these after running `npm run deploy`
+const PACKAGE_ID = process.env.GAME_PACKAGE_ID || '0x_REPLACE_WITH_PACKAGE_ID';
+const GAME_ADMIN_CAP = process.env.GAME_ADMIN_CAP || '0x_REPLACE_WITH_ADMIN_CAP'; // Found in publish output
+
+const MODULE = 'hero';
+
+async function main() {
+    console.log('--- SUI QUEST CLIENT ---');
+
+    const client = new SuiClient({ url: 'https://fullnode.testnet.sui.io' });
+
+    // 1. Account Setup (Session)
+    // In a real app, we'd take a private key from env or wallet adapter 
+    const session = new SessionManager(client);
+    console.log(`Player Session Address: ${session.sessionAddress}`);
+    console.log('Fund this address with Testnet SUI to play!');
+
+    // 2. Listen to the Game
+    const syncer = new GameStateSync(client);
+    console.log(`\nSubscribing to events from package: ${PACKAGE_ID}...`);
+
+    syncer.subscribe(`${PACKAGE_ID}::${MODULE}::AttackEvent`, (event) => {
+        const data = event.parsedJson as any;
+        console.log(`⚔️  Hero dealt ${data.damage_dealt} damage!`);
+    });
+    syncer.subscribe(`${PACKAGE_ID}::${MODULE}::LevelUpEvent`, (event) => {
+        const data = event.parsedJson as any;
+        console.log(`🎉 LEVEL UP! New Level: ${data.new_level}`);
+    });
+
+    console.log('Polling for events...');
+    syncer.startPolling(PACKAGE_ID);
+
+    // 3. Gameplay Loop (Simulation)
+    if (PACKAGE_ID.startsWith('0x_REPLACE')) {
+        console.warn('\n⚠️  Please deploy the contract first and set game package ID in client/index.ts');
+        console.warn('Run: npm run deploy');
+        return;
+    }
+
+    // Demo: Simulation of Action
+    console.log('\n[Simulating "Slay Boar" Action...]');
+    console.log('Note: This will fail if the session wallet has no gas or no Hero object.');
+
+    // In a real game, you would find the Hero object ID owned by the session
+    try {
+        const heroes = await client.getOwnedObjects({
+            owner: session.sessionAddress,
+            options: { showType: true, showContent: true }
+        });
+
+        const heroObj = heroes.data.find(d => d.data?.type === `${PACKAGE_ID}::${MODULE}::Hero`);
+
+        if (heroObj) {
+            const heroId = heroObj.data?.objectId;
+            console.log(`Found Hero: ${heroId}. Attempting to Slay Boar...`);
+
+            const tx = new Transaction();
+            tx.moveCall({
+                target: `${PACKAGE_ID}::${MODULE}::slay_boar`,
+                arguments: [tx.object(heroId!)]
+            });
+            const res = await session.executeSessionTx(tx);
+            console.log('Action Executed! Digest:', res.digest);
+        } else {
+            console.log('No Hero found. You need to mint one first (requires Admin Cap or open minting).');
+            // Mock minting call if we had one open
+        }
+
+    } catch (e) {
+        console.error('Error during simulation:', e);
+    }
+}
+
+main().catch(console.error);

package/starter/move/Move.toml

@@ -0,0 +1,9 @@
+[package]
+name = "SuiQuest"
+version = "0.0.1"
+
+[dependencies]
+Sui = { git = "https://github.com/MystenLabs/sui.git", subdir = "crates/sui-framework/packages/sui-framework", rev = "framework/testnet" }
+
+[addresses]
+sui_quest = "0x0"