sui-game-sdk 0.0.1

package/starter/move/sources/hero.move

@@ -0,0 +1,109 @@
+module sui_quest::hero {
+    use sui::object::{Self, UID};
+    use sui::tx_context::{Self, TxContext};
+    use sui::transfer;
+    use sui::event;
+
+    // --- Structs ---
+
+    struct Hero has key, store {
+        id: UID,
+        name: vector<u8>,
+        level: u64,
+        experience: u64,
+        hp: u64,
+        strength: u64,
+    }
+
+    struct GameAdmin has key {
+        id: UID,
+    }
+
+    // --- Events ---
+
+    struct HeroMinted has copy, drop {
+        id: address,
+        name: vector<u8>,
+        owner: address,
+    }
+
+    struct AttackEvent has copy, drop {
+        hero_id: address,
+        damage_dealt: u64,
+        enemy_hp_remaining: u64, // simplified
+    }
+
+    struct LevelUpEvent has copy, drop {
+        hero_id: address,
+        new_level: u64,
+    }
+
+    // --- Initializer ---
+
+    fun init(ctx: &mut TxContext) {
+        let admin = GameAdmin { id: object::new(ctx) };
+        transfer::transfer(admin, tx_context::sender(ctx));
+    }
+
+    // --- Entry Functions ---
+
+    public entry fun mint_hero(
+        _admin: &GameAdmin, // Require admin to mint (simulate controlled spawning)
+        name: vector<u8>,
+        recipient: address,
+        ctx: &mut TxContext
+    ) {
+        let id = object::new(ctx);
+        let hero_id = object::uid_to_address(&id);
+        
+        let hero = Hero {
+            id,
+            name,
+            level: 1,
+            experience: 0,
+            hp: 100,
+            strength: 10,
+        };
+
+        event::emit(HeroMinted {
+            id: hero_id,
+            name,
+            owner: recipient
+        });
+
+        transfer::public_transfer(hero, recipient);
+    }
+
+    public entry fun slay_boar(hero: &mut Hero, ctx: &mut TxContext) {
+        // Simulate combat logic
+        // In reality, you'd use on-chain randomness or a specific Monster object
+        
+        // 1. Calculate Damage (Strength +/- random noise simulated)
+        let damage = hero.strength + 2; 
+
+        // 2. Grant XP
+        hero.experience = hero.experience + 10;
+        
+        // 3. Check Level Up
+        if (hero.experience >= 100) {
+            hero.level = hero.level + 1;
+            hero.experience = 0;
+            hero.strength = hero.strength + 5;
+            event::emit(LevelUpEvent {
+                hero_id: object::uid_to_address(&hero.id),
+                new_level: hero.level
+            });
+        };
+
+        event::emit(AttackEvent {
+            hero_id: object::uid_to_address(&hero.id),
+            damage_dealt: damage,
+            enemy_hp_remaining: 0 
+        });
+    }
+
+    // --- Accessors (View Functions) ---
+    public fun get_level(hero: &Hero): u64 {
+        hero.level
+    }
+}

package/starter/scripts/deploy.ts

@@ -0,0 +1,37 @@
+import { execSync } from 'child_process';
+import path from 'path';
+
+async function main() {
+    const moveDir = path.resolve(__dirname, '../move');
+    console.log(`Deploying from ${moveDir}...`);
+
+    console.log('Building Move Package...');
+    // This assumes the user has 'sui' CLI installed and in path.
+    // We capture the output JSON to parse the package ID.
+    try {
+        const output = execSync('sui client publish --gas-budget 100000000 --json', {
+            cwd: moveDir,
+            encoding: 'utf-8'
+        });
+
+        const result = JSON.parse(output);
+        const packageId = result.objectChanges.find((c: any) => c.type === 'published')?.packageId;
+
+        if (!packageId) {
+            console.error('Could not find package ID in publish output.');
+            console.log(output);
+            return;
+        }
+
+        console.log('\nSUCCESS! Package Published.');
+        console.log('Package ID:', packageId);
+
+        // You would typically save this to a config file for the client to use.
+        console.log('\nCopy this Package ID to your client config!');
+    } catch (e: any) {
+        console.error('Deployment validation failed:', e.message);
+        console.log('Ensure you have sufficient gas and the SUI CLI configured for the active network.');
+    }
+}
+
+main();

package/starters/godot/README.md

@@ -0,0 +1,71 @@
+# Godot 4 RPG Starter + Sui Game SDK
+
+A Godot 4 starter kit designed to seamlessly integrate with the `sui-game-sdk`.
+
+## 🎮 Features
+- **Godot 4 Architecture**: Uses `Scenes` and `Scripts` in a standard project layout.
+- **Sui Integration**:
+  - `SuiService`: Validates connection and handles RPC calls. Mimics `Session` and `Sync` logic.
+  - `HeroController`: Demonstrates `Spawner` logic for minting and state updates.
+- **Sui Quest**: A sample implementation of the cross-platform hero game.
+- **Independent**: Includes its own Move contract and deployment script.
+
+## 🔥 Quick Start
+
+### Prerequisites
+- Godot 4.2+
+- Node.js (for deploying the contract)
+- Sui CLI installed and configured
+
+### 1. Deploy the Move Contract
+```bash
+# From the Godot starter directory
+node deploy.js
+```
+Copy the **Package ID** output from the deployment.
+
+### 2. Configuration
+1. Open `scripts/sui/hero_controller.gd`.
+2. Update the `GAME_PACKAGE_ID` constant with your deployed contract ID.
+   ```gdscript
+   const GAME_PACKAGE_ID = "0x..."
+   ```
+
+### 3. Open in Godot
+1. Open Godot 4.
+2. Click **Import** and navigate to this folder.
+3. Select `project.godot`.
+
+### 4. Play
+1. Press **F5** (Play Main Scene).
+2. Watch the Output / Debug Console.
+3. Hook up the `mint_hero` and `slay_boar` functions to UI Buttons (not included in starter to keep it unopinionated).
+
+## 🛠 SDK Mapping
+
+| Concept | Godot Script | Description |
+|---|---|---|
+| **Session** | `SuiService` | Manages connection parameters |
+| **Spawner** | `sui_service.spawn_asset` | Creates Move Call payloads to spawn assets |
+| **Sync** | `sui_service.sync_state` | Synchronizes on-chain state to game objects |
+
+## 📁 Project Structure
+
+```
+godot/
+├── project.godot
+├── scenes/
+│   └── main.tscn
+├── scripts/
+│   ├── game_manager.gd
+│   ├── player.gd
+│   └── sui/
+│       ├── sui_service.gd
+│       └── hero_controller.gd
+├── move/                  # Move smart contract
+│   └── sources/
+│       └── hero.move
+└── deploy.js             # Deployment script
+```
+
+> **Pro Tip**: Use this starter as a module. Copy the `scripts/sui` folder into your existing Godot game!

package/starters/godot/deploy.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+
+const { execSync } = require('child_process');
+const path = require('path');
+
+async function main() {
+    const moveDir = path.resolve(__dirname, '../move');
+    console.log(`Deploying from ${moveDir}...`);
+
+    console.log('Building Move Package...');
+    try {
+        const output = execSync('sui client publish --gas-budget 100000000 --json', {
+            cwd: moveDir,
+            encoding: 'utf-8'
+        });
+
+        const result = JSON.parse(output);
+        const packageId = result.objectChanges.find((c) => c.type === 'published')?.packageId;
+        const adminCap = result.objectChanges.find((c) => c.objectType?.includes('GameAdmin'))?.objectId;
+
+        if (!packageId) {
+            console.error('Could not find package ID in publish output.');
+            console.log(output);
+            return;
+        }
+
+        console.log('\nSUCCESS! Package Published.');
+        console.log('Package ID:', packageId);
+        if (adminCap) console.log('Admin Cap:', adminCap);
+
+        console.log('\nUpdate hero_controller.gd:');
+        console.log(`const GAME_PACKAGE_ID = "${packageId}"`);
+    } catch (e) {
+        console.error('Deployment failed:', e.message);
+        console.log('Ensure you have sufficient gas and the SUI CLI configured.');
+    }
+}
+
+main();

package/starters/godot/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"

package/starters/godot/move/sources/hero.move

@@ -0,0 +1,109 @@
+module sui_quest::hero {
+    use sui::object::{Self, UID};
+    use sui::tx_context::{Self, TxContext};
+    use sui::transfer;
+    use sui::event;
+
+    // --- Structs ---
+
+    struct Hero has key, store {
+        id: UID,
+        name: vector<u8>,
+        level: u64,
+        experience: u64,
+        hp: u64,
+        strength: u64,
+    }
+
+    struct GameAdmin has key {
+        id: UID,
+    }
+
+    // --- Events ---
+
+    struct HeroMinted has copy, drop {
+        id: address,
+        name: vector<u8>,
+        owner: address,
+    }
+
+    struct AttackEvent has copy, drop {
+        hero_id: address,
+        damage_dealt: u64,
+        enemy_hp_remaining: u64, // simplified
+    }
+
+    struct LevelUpEvent has copy, drop {
+        hero_id: address,
+        new_level: u64,
+    }
+
+    // --- Initializer ---
+
+    fun init(ctx: &mut TxContext) {
+        let admin = GameAdmin { id: object::new(ctx) };
+        transfer::transfer(admin, tx_context::sender(ctx));
+    }
+
+    // --- Entry Functions ---
+
+    public entry fun mint_hero(
+        _admin: &GameAdmin, // Require admin to mint (simulate controlled spawning)
+        name: vector<u8>,
+        recipient: address,
+        ctx: &mut TxContext
+    ) {
+        let id = object::new(ctx);
+        let hero_id = object::uid_to_address(&id);
+        
+        let hero = Hero {
+            id,
+            name,
+            level: 1,
+            experience: 0,
+            hp: 100,
+            strength: 10,
+        };
+
+        event::emit(HeroMinted {
+            id: hero_id,
+            name,
+            owner: recipient
+        });
+
+        transfer::public_transfer(hero, recipient);
+    }
+
+    public entry fun slay_boar(hero: &mut Hero, ctx: &mut TxContext) {
+        // Simulate combat logic
+        // In reality, you'd use on-chain randomness or a specific Monster object
+        
+        // 1. Calculate Damage (Strength +/- random noise simulated)
+        let damage = hero.strength + 2; 
+
+        // 2. Grant XP
+        hero.experience = hero.experience + 10;
+        
+        // 3. Check Level Up
+        if (hero.experience >= 100) {
+            hero.level = hero.level + 1;
+            hero.experience = 0;
+            hero.strength = hero.strength + 5;
+            event::emit(LevelUpEvent {
+                hero_id: object::uid_to_address(&hero.id),
+                new_level: hero.level
+            });
+        };
+
+        event::emit(AttackEvent {
+            hero_id: object::uid_to_address(&hero.id),
+            damage_dealt: damage,
+            enemy_hp_remaining: 0 
+        });
+    }
+
+    // --- Accessors (View Functions) ---
+    public fun get_level(hero: &Hero): u64 {
+        hero.level
+    }
+}

package/starters/godot/project.godot

@@ -0,0 +1,29 @@
+; Engine configuration file.
+; It's best edited using the editor UI and not directly,
+; since the parameters that go here are not all obvious.
+;
+; Format:
+;   [section] ; section goes between []
+;   param=value ; assign values to parameters
+
+config_version=5
+
+[application]
+
+config/name="Sui Godot RPG"
+run/main_scene="res://scenes/main.tscn"
+config/features=PackedStringArray("4.2", "Forward Plus")
+config/icon="res://icon.svg"
+
+[autoload]
+
+GameManager="*res://scripts/game_manager.gd"
+
+[display]
+
+window/size/viewport_width=1152
+window/size/viewport_height=648
+
+[dotnet]
+
+project/assembly_name="Sui Godot RPG"

package/starters/godot/scenes/main.tscn

@@ -0,0 +1,22 @@
+[gd_scene load_steps=2 format=3 uid="uid://c8q4q8q4q8q4"]
+
+[ext_resource type="Script" path="res://scripts/sui/hero_controller.gd" id="1_hero"]
+
+[node name="Main" type="Node2D"]
+
+[node name="UI" type="Control" parent="."]
+layout_mode = 3
+anchors_preset = 0
+offset_right = 1152.0
+offset_bottom = 648.0
+
+[node name="Label" type="Label" parent="UI"]
+layout_mode = 0
+offset_left = 469.0
+offset_top = 281.0
+offset_right = 684.0
+offset_bottom = 304.0
+text = "Sui Godot Starter"
+
+[node name="HeroController" type="Node" parent="."]
+script = ExtResource("1_hero")

package/starters/godot/scripts/game_manager.gd

@@ -0,0 +1,14 @@
+extends Node
+
+# GameManager.gd
+# Autoloaded global script
+
+var player_score = 0
+var game_active = false
+
+func _ready():
+	print("GameManager initialized.")
+
+func start_game():
+	game_active = true
+	print("Game Started!")

package/starters/godot/scripts/player.gd

@@ -0,0 +1,10 @@
+extends CharacterBody2D
+
+const SPEED = 200.0
+
+func _physics_process(delta):
+	# Simple 4-way movement
+	var direction = Input.get_vector("ui_left", "ui_right", "ui_up", "ui_down")
+	velocity = direction * SPEED
+
+	move_and_slide()

package/starters/godot/scripts/sui/hero_controller.gd

@@ -0,0 +1,56 @@
+extends Node
+
+# HeroController.gd
+# Logic for the Hero game
+
+const GAME_PACKAGE_ID = "0x_REPLACE_WITH_PACKAGE_ID"
+const HERO_MODULE = "hero"
+# In a real game, this comes from the Session/Wallet
+const PLAYER_ADDRESS = "0x_PLAYER_ADDRESS_HERE"
+
+var sui_service: SuiService
+var hero_id = null
+
+func _ready():
+	# Instance the service manually if not autoloaded, or find it
+	sui_service = SuiService.new()
+	add_child(sui_service) # Add to tree to enable processing
+	
+	sui_service.rpc_response.connect(_on_sui_response)
+	
+	# Wait a bit or trigger via UI
+	print("HeroController ready. Call check_hero() to start.")
+	check_hero()
+
+func check_hero():
+	print("Checking for Hero...")
+	sui_service.sync_state(PLAYER_ADDRESS)
+
+func mint_hero():
+	print("Minting Hero...")
+	sui_service.spawn_asset(GAME_PACKAGE_ID, HERO_MODULE, "mint_hero", ["GodotWarrior"], PLAYER_ADDRESS)
+
+func slay_boar():
+	if hero_id:
+		print("Slaying Boar...")
+		sui_service.spawn_asset(GAME_PACKAGE_ID, HERO_MODULE, "slay_boar", [hero_id], PLAYER_ADDRESS)
+	else:
+		print("No Hero to slay with!")
+
+func _on_sui_response(_method, result, error):
+	if error:
+		print("RPC Error: ", error)
+		return
+	
+	# Parse for Hero
+	if result and typeof(result) == TYPE_DICTIONARY and "data" in result:
+		var found = false
+		for obj in result["data"]:
+			var type_str = obj.get("data", {}).get("type", "")
+			if "%s::%s::Hero" % [GAME_PACKAGE_ID, HERO_MODULE] in type_str:
+				hero_id = obj["data"]["objectId"]
+				print("Hero FOUND: ", hero_id)
+				found = true
+				break
+		if not found:
+			print("No hero found.")

package/starters/godot/scripts/sui/sui_service.gd

@@ -0,0 +1,62 @@
+extends Node
+
+# SuiService.gd - Autoload or instanced helper
+class_name SuiService
+
+const RPC_URL = "https://fullnode.testnet.sui.io"
+var http_request: HTTPRequest
+signal rpc_response(method, result, error)
+
+func _ready():
+	http_request = HTTPRequest.new()
+	add_child(http_request)
+	http_request.request_completed.connect(_on_request_completed)
+	print("[SuiService] Ready.")
+
+func get_owned_objects(address: String):
+	# Request objects with Type info
+	var method = "suix_getOwnedObjects"
+	var params = [address, { "options": { "showType": true } }]
+	send_rpc(method, params)
+
+func construct_move_call(package: String, module: String, function: String, args: Array, sender: String):
+	return spawn_asset(package, module, function, args, sender)
+
+# Spawns asset / executes move call (AssetSpawner concept from SDK)
+func spawn_asset(package: String, module: String, function: String, args: Array, sender: String):
+	var payload = {
+		"target": "%s::%s::%s" % [package, module, function],
+		"arguments": args,
+		"sender": sender,
+		"type": "move_call"
+	}
+	print("[SuiService] Asset Spawn Payload: ", JSON.stringify(payload))
+	return payload
+
+# Syncs game state (GameStateSync concept from SDK)
+func sync_state(address: String):
+	var method = "suix_getOwnedObjects"
+	var params = [address, { "options": { "showType": true } }]
+	send_rpc(method, params)
+
+func send_rpc(method: String, params: Array):
+	var body = JSON.stringify({
+		"jsonrpc": "2.0", 
+		"id": 1, 
+		"method": method, 
+		"params": params
+	})
+	var headers = ["Content-Type: application/json"]
+	var err = http_request.request(RPC_URL, headers, HTTPClient.METHOD_POST, body)
+	if err != OK:
+		emit_signal("rpc_response", method, null, "HTTP Request Failed")
+
+func _on_request_completed(_result, response_code, _headers, body):
+	if response_code == 200:
+		var json = JSON.parse_string(body.get_string_from_utf8())
+		if "error" in json:
+			emit_signal("rpc_response", "unknown", null, json["error"])
+		else:
+			emit_signal("rpc_response", "unknown", json["result"], null) 
+	else:
+		emit_signal("rpc_response", "unknown", null, str(response_code))

package/starters/nextjs/.env.local.example

@@ -0,0 +1,2 @@
+NEXT_PUBLIC_PACKAGE_ID=0x_REPLACE_WITH_PACKAGE_ID
+NEXT_PUBLIC_ADMIN_CAP=0x_REPLACE_WITH_ADMIN_CAP

package/starters/nextjs/README.md

@@ -0,0 +1,110 @@
+# Next.js Game Starter + Sui Game SDK
+
+A modern Next.js 14 web game that **directly uses** the `sui-game-sdk` package.
+
+## ✨ Features
+- **Direct SDK Integration**: Uses actual `SessionManager`, `AssetSpawner`, and `GameStateSync` from sui-game-sdk
+- **Modern Stack**: Next.js 14 App Router + TypeScript + Tailwind CSS
+- **Real-time Events**: Live event streaming from the blockchain
+- **Beautiful UI**: Glassmorphic design with gradients and animations
+
+## 🚀 Quick Start
+
+### 1. Deploy the Move Contract
+```bash
+npm install
+npm run deploy
+```
+Copy the **Package ID** and **Admin Cap** from the output.
+
+### 2. Configure Environment
+Copy the example env file:
+```bash
+cp .env.local.example .env.local
+```
+
+Edit `.env.local` and add your deployed contract details:
+```env
+NEXT_PUBLIC_PACKAGE_ID=0x...  # Your deployed package ID
+NEXT_PUBLIC_ADMIN_CAP=0x...   # Your admin cap ID
+```
+
+### 3. Run Development Server
+```bash
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) in your browser.
+
+## 📦 How It Uses sui-game-sdk
+
+This starter demonstrates **direct usage** of the SDK:
+
+### Session Management
+```typescript
+import { SessionManager } from 'sui-game-sdk';
+
+const sessionManager = new SessionManager(suiClient);
+console.log(sessionManager.sessionAddress); // Auto-generated session wallet
+```
+
+### Asset Spawning
+```typescript
+import { AssetSpawner } from 'sui-game-sdk';
+
+const spawner = new AssetSpawner(suiClient, {
+    packageId: PACKAGE_ID,
+    module: 'hero',
+    function: 'mint_hero',
+    adminCapId: ADMIN_CAP
+});
+```
+
+### Game State Sync
+```typescript
+import { GameStateSync } from 'sui-game-sdk';
+
+const sync = new GameStateSync(suiClient);
+
+sync.subscribe('AttackEvent', (event) => {
+    console.log('Damage:', event.parsedJson.damage_dealt);
+});
+
+sync.startPolling(PACKAGE_ID);
+```
+
+## 🎮 Game Flow
+
+1. **Session Created**: Automatic on page load
+2. **Hero Check**: Queries blockchain for existing hero
+3. **Mint Hero**: Creates a new hero NFT (requires admin cap)
+4. **Slay Boar**: Executes on-chain action, earns XP
+5. **Level Up**: Automatic when XP threshold reached
+
+## 🏗️ Project Structure
+
+```
+nextjs/
+├── app/
+│   ├── layout.tsx       # Root layout
+│   ├── page.tsx         # Main page
+│   └── globals.css      # Global styles
+├── components/
+│   └── HeroGame.tsx     # Main game component
+├── lib/
+│   └── sui-client.ts    # SDK initialization
+└── package.json
+```
+
+## 🔧 Build for Production
+
+```bash
+npm run build
+npm start
+```
+
+## 📝 Notes
+
+- This is a **client-side** app. Session keys are generated in the browser.
+- For production, integrate a proper wallet adapter (e.g., Sui Wallet, Ethos).
+- The SDK handles all blockchain interactions seamlessly.

package/starters/nextjs/app/globals.css

@@ -0,0 +1,3 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;