@myvillage/cli 1.51.0 → 1.61.0

package/src/utils/templates.js

@@ -1,5 +1,39 @@
 import { mkdirSync, writeFileSync } from 'fs';
 import { join } from 'path';
+import { randomUUID } from 'crypto';
+
+// GameKit SDK version that scaffolded Unity projects pin to.
+// Bump alongside CLI minor releases as the SDK contract evolves.
+const GAMEKIT_SDK_VERSION = '1.1.0-alpha.4';
+const GAMEKIT_SDK_URL =
+  `https://github.com/MyVillage-Project-Technologies/myvillage-gamekit.git#v${GAMEKIT_SDK_VERSION}`;
+
+// Fallback Unity Editor version used only if we can't fetch the SDK's
+// package.json at scaffold time. The SDK declares the recommended editor
+// version via `unity` + `unityRelease` fields — that's the source of truth.
+const UNITY_EDITOR_VERSION_FALLBACK = '6000.3.12f1';
+
+const SDK_PACKAGE_JSON_RAW_URL =
+  `https://raw.githubusercontent.com/MyVillage-Project-Technologies/myvillage-gamekit/v${GAMEKIT_SDK_VERSION}/package.json`;
+
+// Resolve the Unity Editor version from the SDK's package.json. Combines the
+// UPM `unity` ("MAJOR.MINOR") and `unityRelease` ("PATCHfINCR") fields into a
+// full version string like "6000.0.76f1". Falls back on any failure so
+// offline scaffolding still works.
+async function resolveUnityVersion() {
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 5000);
+    const res = await fetch(SDK_PACKAGE_JSON_RAW_URL, { signal: controller.signal });
+    clearTimeout(timeout);
+    if (!res.ok) return UNITY_EDITOR_VERSION_FALLBACK;
+    const pkg = await res.json();
+    if (pkg.unity && pkg.unityRelease) return `${pkg.unity}.${pkg.unityRelease}`;
+    return UNITY_EDITOR_VERSION_FALLBACK;
+  } catch {
+    return UNITY_EDITOR_VERSION_FALLBACK;
+  }
+}
 
 // MyVillage brand colors
 const BRAND = {
@@ -68,15 +102,25 @@ export function createGameProject(targetDir, options) {
 
 // ── Unity Game Project ─────────────────────────────────────────────
 
-export function createUnityGameProject(targetDir, options) {
-  const { name, description, type, ageGroup, platform } = options;
+export async function createUnityGameProject(targetDir, options) {
+  const { name, description, type, ageGroup, platform, unityVersion: explicitUnityVersion } = options;
   const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, '');
   const className = name.replace(/[^a-zA-Z0-9]/g, '');
+  const unityVersion = explicitUnityVersion || await resolveUnityVersion();
+
+  // Scaffold an openable Unity project that pulls com.myvillage.gamekit via UPM.
+  // Layout matches what Unity Hub expects:
+  //   Packages/manifest.json       - dependency on the GameKit SDK + core modules
+  //   ProjectSettings/ProjectVersion.txt - tells Unity which editor version
+  //   Assets/Scripts/<Name>.cs     - starter MissionBase subclass
+  //   builds/{ios,android,webgl}/  - drop-zone for builds the CLI deploys
 
   const dirs = [
     '',
-    'Scripts',
-    'Scripts/MyVillageOS',
+    'Assets',
+    'Assets/Scripts',
+    'Packages',
+    'ProjectSettings',
     'builds',
     'builds/ios',
     'builds/android',
@@ -87,7 +131,7 @@ export function createUnityGameProject(targetDir, options) {
     mkdirSync(join(targetDir, dir), { recursive: true });
   }
 
-  // Config file (CLI reads this instead of package.json for Unity projects)
+  // CLI metadata. gameId/lastDeployed are populated by deploy.
   writeFileSync(join(targetDir, 'myvillage.json'), JSON.stringify({
     name,
     slug,
@@ -96,575 +140,198 @@ export function createUnityGameProject(targetDir, options) {
     gameType: platform === 'webgl' ? 'UNITY_WEBGL' : 'UNITY_NATIVE',
     category: type.toUpperCase(),
     targetAge: ageGroup,
+    sdkVersion: GAMEKIT_SDK_VERSION,
+    unityVersion,
     gameId: null,
     lastDeployed: null,
   }, null, 2) + '\n');
 
-  writeFileSync(join(targetDir, '.gitignore'), [
-    'builds/*/*.meta', 'Library/', 'Temp/', 'Logs/', 'obj/',
-    'UserSettings/', '.vs/', '*.csproj', '*.sln',
-  ].join('\n') + '\n');
+  // Unity project files.
+  writeFileSync(join(targetDir, 'Packages/manifest.json'), generateUnityPackagesManifest());
+  writeFileSync(join(targetDir, 'ProjectSettings/ProjectVersion.txt'), generateUnityProjectVersion(unityVersion));
 
-  // MyVillageOS integration scripts
-  writeFileSync(join(targetDir, 'Scripts/MyVillageOS/EdPlatformConfig.cs'), generateEdPlatformConfig());
-  writeFileSync(join(targetDir, 'Scripts/MyVillageOS/GameSessionReporter.cs'), generateGameSessionReporter());
-  writeFileSync(join(targetDir, 'Scripts/MyVillageOS/MyVillageAuth.cs'), generateMyVillageAuth());
-  writeFileSync(join(targetDir, 'Scripts/MyVillageOS/PKCEHelper.cs'), generatePKCEHelper());
-  writeFileSync(join(targetDir, 'Scripts/MyVillageOS/MyVillageEvents.cs'), generateMyVillageEvents());
+  // Starter mission. New devs subclass MissionBase here.
+  writeFileSync(join(targetDir, `Assets/Scripts/${className}.cs`), generateMissionScript(className, name, unityVersion));
+  writeFileSync(join(targetDir, `Assets/Scripts/${className}.cs.meta`), generateUnityScriptMeta());
 
-  // Game-specific loader template
-  writeFileSync(join(targetDir, `Scripts/${className}Loader.cs`), generateGameLoader(className, slug));
+  writeFileSync(join(targetDir, '.gitignore'), generateUnityGitignore());
+  writeFileSync(join(targetDir, 'README.md'), generateUnityReadme(name, slug, className, platform, unityVersion));
 
-  // README
-  writeFileSync(join(targetDir, 'README.md'), generateUnityReadme(name, slug, className, platform));
+  return { unityVersion, sdkVersion: GAMEKIT_SDK_VERSION };
 }
 
-function generateEdPlatformConfig() {
-  return `using UnityEngine;
-using UnityEngine.Networking;
-
-/// <summary>
-/// MyVillageOS ed-platform API configuration.
-/// All endpoints use dynamic game slugs — no hardcoded game IDs.
-/// </summary>
-public static class EdPlatformConfig
-{
-    private const string ProductionUrl = "https://portal.myvillageproject.ai";
-    private const string DevelopmentUrl = "http://localhost:3000";
-
-    public static string BaseUrl
-    {
-        get
-        {
-#if UNITY_EDITOR || DEVELOPMENT_BUILD
-            return DevelopmentUrl;
-#else
-            return ProductionUrl;
-#endif
-        }
-    }
-
-    // Game catalog
-    public static string GamesListEndpoint => $"{BaseUrl}/api/v1/games";
-
-    // Per-game sessions
-    public static string SessionsEndpoint(string gameSlug) =>
-        $"{BaseUrl}/api/v1/games/{gameSlug}/sessions";
-
-    public static string SessionCompleteEndpoint(string gameSlug, string sessionId) =>
-        $"{SessionsEndpoint(gameSlug)}/{sessionId}/complete";
-
-    // Bundle URLs
-    public static string BundleUrl(string gameSlug, string bundleName)
-    {
-        string escaped = UnityWebRequest.EscapeURL(bundleName.ToLower());
-        return $"{BaseUrl}/api/v1/games/game-assets/games/{gameSlug}/bundles/{CurrentPlatform}/{escaped}";
-    }
+// ── Unity (GameKit SDK) ─────────────────────────────────────────────
 
-    public static string CurrentPlatform
-    {
-        get
-        {
-#if UNITY_IOS
-            return "ios";
-#elif UNITY_ANDROID
-            return "android";
-#elif UNITY_WEBGL
-            return "webgl";
-#else
-            return "desktop";
-#endif
-        }
-    }
-}
-`;
+function generateUnityPackagesManifest() {
+  return JSON.stringify({
+    dependencies: {
+      'com.myvillage.gamekit': GAMEKIT_SDK_URL,
+      'com.unity.feature.development': '1.0.2',
+      'com.unity.render-pipelines.universal': '17.2.0',
+      'com.unity.textmeshpro': '3.0.6',
+      'com.unity.inputsystem': '1.14.2',
+      'com.unity.ide.rider': '3.0.38',
+      'com.unity.ide.visualstudio': '2.0.22',
+    },
+  }, null, 2) + '\n';
 }
 
-function generateGameSessionReporter() {
-  return `using UnityEngine;
-using UnityEngine.Networking;
-using System;
-using System.Collections;
-using System.Text;
-
-/// <summary>
-/// Manages game session lifecycle with the MyVillageOS ed-platform.
-/// Attach to a persistent GameObject. Call StartSession() when gameplay
-/// begins and CompleteSession() when the player finishes.
-/// </summary>
-public class GameSessionReporter : MonoBehaviour
-{
-    public static GameSessionReporter Instance { get; private set; }
-
-    [Header("Game Settings")]
-    [Tooltip("Your game's slug on the ed-platform (e.g. 'eternal-equations')")]
-    public string GameSlug;
-
-    private string currentSessionId;
-    private float sessionStartTime;
-
-    void Awake()
-    {
-        if (Instance != null && Instance != this) { Destroy(gameObject); return; }
-        Instance = this;
-        DontDestroyOnLoad(gameObject);
-    }
-
-    /// <summary>Start a new play session. Call when gameplay begins.</summary>
-    public void StartSession()
-    {
-        if (string.IsNullOrEmpty(GameSlug))
-        {
-            Debug.LogWarning("[MyVillageOS] GameSlug not set on GameSessionReporter");
-            return;
-        }
-        StartCoroutine(StartSessionCoroutine());
-    }
-
-    /// <summary>Complete the current session with a score. Call when the player finishes.</summary>
-    public void CompleteSession(int score, int correct = 0, int incorrect = 0, string difficulty = "medium")
-    {
-        if (string.IsNullOrEmpty(currentSessionId))
-        {
-            Debug.LogWarning("[MyVillageOS] No active session to complete");
-            return;
-        }
-        StartCoroutine(CompleteSessionCoroutine(score, correct, incorrect, difficulty));
-    }
-
-    private IEnumerator StartSessionCoroutine()
-    {
-        string url = EdPlatformConfig.SessionsEndpoint(GameSlug);
-        string json = JsonUtility.ToJson(new SessionStartRequest { platform = EdPlatformConfig.CurrentPlatform });
-
-        using (var req = new UnityWebRequest(url, "POST"))
-        {
-            req.uploadHandler = new UploadHandlerRaw(Encoding.UTF8.GetBytes(json));
-            req.downloadHandler = new DownloadHandlerBuffer();
-            req.SetRequestHeader("Content-Type", "application/json");
-            AddAuthHeader(req);
-
-            yield return req.SendWebRequest();
-
-            if (req.result == UnityWebRequest.Result.Success)
-            {
-                var response = JsonUtility.FromJson<SessionStartResponse>(req.downloadHandler.text);
-                currentSessionId = response.session?.id;
-                sessionStartTime = Time.realtimeSinceStartup;
-                MyVillageEvents.OnSessionStarted?.Invoke(currentSessionId);
-                Debug.Log($"[MyVillageOS] Session started: {currentSessionId}");
-            }
-            else
-            {
-                Debug.LogWarning($"[MyVillageOS] Failed to start session: {req.error}");
-            }
-        }
-    }
-
-    private IEnumerator CompleteSessionCoroutine(int score, int correct, int incorrect, string difficulty)
-    {
-        string url = EdPlatformConfig.SessionCompleteEndpoint(GameSlug, currentSessionId);
-        int duration = Mathf.RoundToInt(Time.realtimeSinceStartup - sessionStartTime);
-
-        var body = new SessionCompleteRequest
-        {
-            score = score,
-            duration = duration,
-            sessionData = new SessionData { correct = correct, incorrect = incorrect, difficulty = difficulty }
-        };
-
-        string json = JsonUtility.ToJson(body);
-
-        using (var req = new UnityWebRequest(url, "POST"))
-        {
-            req.uploadHandler = new UploadHandlerRaw(Encoding.UTF8.GetBytes(json));
-            req.downloadHandler = new DownloadHandlerBuffer();
-            req.SetRequestHeader("Content-Type", "application/json");
-            AddAuthHeader(req);
-
-            yield return req.SendWebRequest();
-
-            if (req.result == UnityWebRequest.Result.Success)
-            {
-                var response = JsonUtility.FromJson<SessionCompleteResponse>(req.downloadHandler.text);
-                int mvt = response.mvtAwarded;
-                MyVillageEvents.OnSessionCompleted?.Invoke(score, duration);
-                if (mvt > 0) MyVillageEvents.OnMVTAwarded?.Invoke(mvt);
-                Debug.Log($"[MyVillageOS] Session complete. Score: {score}, MVT: {mvt}");
-            }
-            else
-            {
-                Debug.LogWarning($"[MyVillageOS] Failed to complete session: {req.error}");
-            }
-        }
-
-        currentSessionId = null;
-    }
-
-    private void AddAuthHeader(UnityWebRequest req)
-    {
-        string token = PlayerPrefs.GetString("jwt_token", "");
-        if (!string.IsNullOrEmpty(token))
-            req.SetRequestHeader("Authorization", $"Bearer {token}");
-    }
-
-    // ── Request/Response DTOs ──
-
-    [Serializable] private class SessionStartRequest { public string platform; }
-    [Serializable] private class SessionStartResponse { public SessionInfo session; }
-    [Serializable] private class SessionInfo { public string id; }
-    [Serializable] private class SessionCompleteRequest { public int score; public int duration; public SessionData sessionData; }
-    [Serializable] private class SessionData { public int correct; public int incorrect; public string difficulty; }
-    [Serializable] private class SessionCompleteResponse { public int mvtAwarded; public bool rewardSkipped; }
-}
-`;
+function generateUnityProjectVersion(unityVersion) {
+  return `m_EditorVersion: ${unityVersion}\n`;
 }
 
-function generateMyVillageAuth() {
-  return `using UnityEngine;
-using UnityEngine.Networking;
-using System;
-using System.Collections;
-using System.Text;
+function generateMissionScript(className, displayName, unityVersion) {
+  return `using MyVillage.GameKit;
+using UnityEngine;
 
 /// <summary>
-/// OAuth 2.0 + PKCE authentication with MyVillageOS.
-/// Call SignIn() to open the browser login flow. The JWT token is
-/// stored in PlayerPrefs and used automatically by GameSessionReporter.
+/// ${displayName} — your MyVillage mission entry point.
+///
+/// FIRST-TIME SETUP (after \`myvillage create-game\` scaffolds this project):
+///   1. Open this project in Unity ${unityVersion}.
+///   2. Click the menu MyVillage -> Create Starter Mission Scene.
+///      Unity creates a scene with a Mission GameObject that already has
+///      MockMissionHost attached and this ${className} component
+///      auto-attached (if it's the only MissionBase in the project).
+///   3. Press Play. Your mission runs end-to-end in the editor — MockMissionHost
+///      stands in for the real M-UNI app, logs every host call to the Console,
+///      and pops up the ResultPanel when CompleteMission fires.
+///
+/// AFTER YOU SHIP TO M-UNI: this same script runs unchanged. The real host
+/// (M-UNI Universe) supplies a MissionHostAdapter that talks to the
+/// ed-platform — sessions, MVT awards, the catalog return — all happen
+/// automatically. You don't change a line.
+///
+/// EDIT THIS SCRIPT: replace OnBegin with your game logic and call
+/// CompleteMission(score) when the player finishes.
 /// </summary>
-public class MyVillageAuth : MonoBehaviour
+public sealed class ${className} : MissionBase
 {
-    public static MyVillageAuth Instance { get; private set; }
-
-    private const string ClientId = "mvos_0L7avBZtpKSIyAT_kZT0Lg";
-    private const string Scopes = "openid profile email phone villager offline_access";
-
-    private string codeVerifier;
-    private string state;
-
-    public bool IsSignedIn => !string.IsNullOrEmpty(PlayerPrefs.GetString("jwt_token", ""));
-
-    void Awake()
-    {
-        if (Instance != null && Instance != this) { Destroy(gameObject); return; }
-        Instance = this;
-        DontDestroyOnLoad(gameObject);
-    }
-
-    /// <summary>Open the MyVillageOS login page in the system browser.</summary>
-    public void SignIn()
-    {
-        codeVerifier = PKCEHelper.GenerateCodeVerifier();
-        string codeChallenge = PKCEHelper.GenerateCodeChallenge(codeVerifier);
-        state = Guid.NewGuid().ToString("N");
-
-        string redirectUri = GetRedirectUri();
-        string url = $"{EdPlatformConfig.BaseUrl}/api/oauth/authorize" +
-            $"?response_type=code&client_id={ClientId}" +
-            $"&redirect_uri={UnityWebRequest.EscapeURL(redirectUri)}" +
-            $"&scope={UnityWebRequest.EscapeURL(Scopes)}" +
-            $"&code_challenge={codeChallenge}&code_challenge_method=S256" +
-            $"&state={state}";
-
-        Application.OpenURL(url);
-    }
-
-    /// <summary>Call this when you receive the auth callback with a code.</summary>
-    public void HandleCallback(string code, string returnedState)
-    {
-        if (returnedState != state)
-        {
-            Debug.LogError("[MyVillageOS] OAuth state mismatch — possible CSRF attack");
-            return;
-        }
-        StartCoroutine(ExchangeCodeForToken(code));
-    }
-
-    /// <summary>Clear the stored token.</summary>
-    public void SignOut()
-    {
-        PlayerPrefs.DeleteKey("jwt_token");
-        PlayerPrefs.DeleteKey("refresh_token");
-        PlayerPrefs.Save();
-        MyVillageEvents.OnSignedOut?.Invoke();
-    }
+    [Header("Mission Settings")]
+    [Tooltip("Seconds before the mission auto-completes. Replace with your own end condition.")]
+    [SerializeField] private float durationSeconds = 30f;
 
-    private IEnumerator ExchangeCodeForToken(string code)
-    {
-        string url = $"{EdPlatformConfig.BaseUrl}/api/oauth/token";
-        string body = $"grant_type=authorization_code&code={code}" +
-            $"&redirect_uri={UnityWebRequest.EscapeURL(GetRedirectUri())}" +
-            $"&client_id={ClientId}&code_verifier={codeVerifier}";
-
-        using (var req = new UnityWebRequest(url, "POST"))
-        {
-            req.uploadHandler = new UploadHandlerRaw(Encoding.UTF8.GetBytes(body));
-            req.downloadHandler = new DownloadHandlerBuffer();
-            req.SetRequestHeader("Content-Type", "application/x-www-form-urlencoded");
-            req.timeout = 15;
-
-            yield return req.SendWebRequest();
-
-            if (req.result == UnityWebRequest.Result.Success)
-            {
-                var token = JsonUtility.FromJson<TokenResponse>(req.downloadHandler.text);
-                PlayerPrefs.SetString("jwt_token", token.access_token);
-                if (!string.IsNullOrEmpty(token.refresh_token))
-                    PlayerPrefs.SetString("refresh_token", token.refresh_token);
-                PlayerPrefs.Save();
-                MyVillageEvents.OnSignedIn?.Invoke();
-                Debug.Log("[MyVillageOS] Signed in successfully");
-            }
-            else
-            {
-                Debug.LogError($"[MyVillageOS] Token exchange failed: {req.error}");
-            }
-        }
-    }
+    [Tooltip("Score reported when the mission finishes.")]
+    [SerializeField] private int finalScore = 100;
 
-    private string GetRedirectUri()
+    protected override void OnBegin()
     {
-#if UNITY_EDITOR || UNITY_STANDALONE
-        return "http://localhost:8429/auth/callback";
-#else
-        // Replace with your app's deep link scheme
-        return "myvillagegame://auth/callback";
-#endif
+        Host.LogEvent("mission.begin");
+        Invoke(nameof(Finish), durationSeconds);
     }
 
-    [Serializable] private class TokenResponse
+    private void Finish()
     {
-        public string access_token;
-        public string refresh_token;
-        public int expires_in;
+        CompleteMission(finalScore: finalScore);
     }
 }
 `;
 }
 
-function generatePKCEHelper() {
-  return `using System;
-using System.Security.Cryptography;
-using System.Text;
-
-/// <summary>PKCE (Proof Key for Code Exchange) helper for OAuth 2.0.</summary>
-public static class PKCEHelper
-{
-    public static string GenerateCodeVerifier()
-    {
-        byte[] bytes = new byte[32];
-        using (var rng = RandomNumberGenerator.Create()) { rng.GetBytes(bytes); }
-        return Convert.ToBase64String(bytes)
-            .TrimEnd('=').Replace('+', '-').Replace('/', '_');
-    }
-
-    public static string GenerateCodeChallenge(string codeVerifier)
-    {
-        using (var sha256 = SHA256.Create())
-        {
-            byte[] hash = sha256.ComputeHash(Encoding.ASCII.GetBytes(codeVerifier));
-            return Convert.ToBase64String(hash)
-                .TrimEnd('=').Replace('+', '-').Replace('/', '_');
-        }
-    }
-}
+function generateUnityScriptMeta() {
+  const guid = randomUUID().replace(/-/g, '');
+  return `fileFormatVersion: 2
+guid: ${guid}
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData:
+  assetBundleName:
+  assetBundleVariant:
 `;
 }
 
-function generateMyVillageEvents() {
-  return `using System;
-
-/// <summary>
-/// Global events for MyVillageOS integration.
-/// Subscribe to these in your game scripts to react to auth and session changes.
-/// </summary>
-public static class MyVillageEvents
-{
-    // Auth
-    public static Action OnSignedIn;
-    public static Action OnSignedOut;
-
-    // Sessions
-    public static Action<string> OnSessionStarted;      // sessionId
-    public static Action<int, int> OnSessionCompleted;   // score, duration
-    public static Action<int> OnMVTAwarded;              // amount
-}
-`;
-}
-
-function generateGameLoader(className, slug) {
-  return `using UnityEngine;
-using UnityEngine.Networking;
-using System.Collections;
-
-/// <summary>
-/// Downloads and loads the AssetBundle for this mini-game.
-/// Attach to a GameObject in your loading scene.
-/// Set AssetName in the Inspector to your bundle file name.
-///
-/// Game slug: "${slug}"
-/// </summary>
-public class ${className}Loader : MonoBehaviour
-{
-    [Header("Bundle Settings")]
-    [Tooltip("The AssetBundle file name (e.g. 'my-game')")]
-    public string AssetName;
-
-    [Tooltip("The scene name inside the AssetBundle to load")]
-    public string SceneName;
-
-    private const string GameSlug = "${slug}";
-
-    void Start()
-    {
-        if (!string.IsNullOrEmpty(AssetName))
-            StartCoroutine(LoadBundle());
-    }
-
-    private IEnumerator LoadBundle()
-    {
-        string url = EdPlatformConfig.BundleUrl(GameSlug, AssetName);
-        Debug.Log($"[${className}Loader] Downloading bundle from: {url}");
-
-        using (var req = UnityWebRequestAssetBundle.GetAssetBundle(url))
-        {
-            var op = req.SendWebRequest();
-
-            while (!op.isDone)
-            {
-                // You can update a progress bar here: req.downloadProgress
-                yield return null;
-            }
-
-            if (req.result != UnityWebRequest.Result.Success)
-            {
-                Debug.LogError($"[${className}Loader] Bundle download failed: {req.error}");
-                yield break;
-            }
-
-            AssetBundle bundle = DownloadHandlerAssetBundle.GetContent(req);
-
-            // Start a game session
-            if (GameSessionReporter.Instance != null)
-            {
-                GameSessionReporter.Instance.GameSlug = GameSlug;
-                GameSessionReporter.Instance.StartSession();
-            }
-
-            // Load the scene from the bundle
-            if (!string.IsNullOrEmpty(SceneName))
-            {
-                string[] scenes = bundle.GetAllScenePaths();
-                if (scenes.Length > 0)
-                    UnityEngine.SceneManagement.SceneManager.LoadScene(scenes[0]);
-            }
-        }
-    }
-
-    /// <summary>
-    /// Call this when the player finishes your game.
-    /// It reports the score to MyVillageOS and awards MVT tokens.
-    /// </summary>
-    public void OnGameComplete(int score, int correct = 0, int incorrect = 0)
-    {
-        if (GameSessionReporter.Instance != null)
-            GameSessionReporter.Instance.CompleteSession(score, correct, incorrect);
-    }
-}
-`;
+function generateUnityGitignore() {
+  return [
+    '# Unity',
+    'Library/',
+    'Temp/',
+    'Obj/',
+    'Logs/',
+    'MemoryCaptures/',
+    'UserSettings/',
+    'Build/',
+    '',
+    '# Editor / IDE',
+    '.vs/',
+    '.idea/',
+    '*.csproj',
+    '*.sln',
+    '*.suo',
+    '*.user',
+    '',
+    '# OS',
+    '.DS_Store',
+    'Thumbs.db',
+    '',
+    '# Built bundles are checked into the deploy artifact, not the repo',
+    'builds/*/*.meta',
+  ].join('\n') + '\n';
 }
 
-function generateUnityReadme(name, slug, className, platform) {
+function generateUnityReadme(name, slug, className, platform, unityVersion) {
   const gameType = platform === 'webgl' ? 'UNITY_WEBGL' : 'UNITY_NATIVE';
+  const buildHint = platform === 'webgl'
+    ? `4. Build to \`builds/webgl/\` via **File -> Build Settings -> WebGL**, then \`myvillage deploy --platform webgl\``
+    : `4. Build AssetBundles to \`builds/ios/\` or \`builds/android/\` via **MyVillage -> Build Mission Bundle**, then \`myvillage deploy --platform ios\` (or \`android\`)`;
+
   return `# ${name}
 
-A MyVillageOS mini-game built with Unity.
+A MyVillage game scaffolded with the MyVillage CLI and the MyVillage GameKit SDK.
 
 - **Slug:** \`${slug}\`
-- **Game Type:** \`${gameType}\`
-- **Platform:** ${platform || 'ios / android'}
-
-## Setup
+- **Game type:** \`${gameType}\`
+- **SDK:** \`com.myvillage.gamekit\` (pinned in \`Packages/manifest.json\`)
 
-1. Open your Unity project (or create a new one)
-2. Copy the \`Scripts/\` folder into your Unity project's \`Assets/\` directory
-3. Create a GameObject and attach \`GameSessionReporter\` — set GameSlug to \`${slug}\`
-4. Create a GameObject and attach \`MyVillageAuth\` (for player sign-in)
-5. Build your game scenes
+## What's in this project
 
-## MyVillageOS Integration
+\`\`\`
+Assets/
+\u2514\u2500\u2500 Scripts/
+    \u2514\u2500\u2500 ${className}.cs       \u2190 your mission, subclasses MissionBase
+Packages/
+\u2514\u2500\u2500 manifest.json         \u2190 fetches the GameKit SDK on first open
+ProjectSettings/
+\u2514\u2500\u2500 ProjectVersion.txt
+myvillage.json               \u2190 CLI metadata (auto-updated by deploy)
+\`\`\`
 
-The generated scripts handle:
+## Quickstart \u2014 play your mission in 3 steps
 
-| Script | Purpose |
-|--------|---------|
-| \`EdPlatformConfig.cs\` | API URL construction (auto-detects platform) |
-| \`GameSessionReporter.cs\` | Session start/complete + MVT rewards |
-| \`MyVillageAuth.cs\` | OAuth 2.0 + PKCE sign-in via browser |
-| \`PKCEHelper.cs\` | Crypto utilities for OAuth PKCE |
-| \`MyVillageEvents.cs\` | Global events (OnSignedIn, OnSessionCompleted, OnMVTAwarded) |
-| \`${className}Loader.cs\` | Downloads your AssetBundle from the ed-platform |
+1. **Install Unity Hub** and Unity **${unityVersion}** if you don't have it. Open this folder in Unity Hub (Add \u2192 Add project from disk). Unity fetches the GameKit SDK automatically (check Package Manager \u2192 In Project).
 
-## Building AssetBundles
+2. **Click the menu \`MyVillage \u2192 Create Starter Mission Scene\`.** This creates a new scene with a "Mission" GameObject that already has \`MockMissionHost\` attached (the editor stand-in for the real M-UNI host) and your \`${className}\` script auto-attached. The scene is added to Build Settings and opened for you.
 
-### For Mobile (iOS / Android)
+3. **Press Play.** Your mission runs end-to-end in the editor. \`MockMissionHost\` logs every host call to the Console and pops up the \`ResultPanel\` when \`CompleteMission\` fires.
 
-1. In Unity: **Assets → Build AssetBundles** (or use your build script)
-2. Output bundles to \`builds/ios/\` and/or \`builds/android/\`
-3. Deploy: \`myvillage deploy --platform ios\`
+Edit \`Assets/Scripts/${className}.cs\`, hit Play again, iterate.
 
-### For Web (WebGL)
+> **What's MockMissionHost?** It's a stand-in for the real M-UNI app. The mission calls \`Host.CompleteMission(score)\` \u2014 in production that goes to the M-UNI app, which records the session and awards MVT. \`MockMissionHost\` is a fake host for editor previews: it logs the call and shows the result UI, but doesn't touch the network. Without it, "Press Play" wouldn't work at all because nothing would call \`Initialize\` on your mission. It's safe to leave attached when you deploy \u2014 the real host overrides it.
 
-1. In Unity: **File → Build Settings → WebGL → Build**
-2. Output to \`builds/webgl/\`
-3. Deploy: \`myvillage deploy --platform webgl\`
+## Building and deploying
 
-## Reporting Scores
+${buildHint}
 
-When the player finishes your game, call:
+Your game is auto-submitted for review on successful deploy. Check status:
 
-\`\`\`csharp
-// From any script:
-GameSessionReporter.Instance.CompleteSession(
-    score: 850,
-    correct: 8,
-    incorrect: 2,
-    difficulty: "medium"
-);
+\`\`\`
+myvillage status
 \`\`\`
 
-This reports the score to MyVillageOS and awards MVT tokens to the player.
-
-## Listening to Events
-
-\`\`\`csharp
-void OnEnable()
-{
-    MyVillageEvents.OnMVTAwarded += ShowRewardPopup;
-    MyVillageEvents.OnSessionCompleted += OnGameDone;
-}
-
-void OnDisable()
-{
-    MyVillageEvents.OnMVTAwarded -= ShowRewardPopup;
-    MyVillageEvents.OnSessionCompleted -= OnGameDone;
-}
+## Editing your mission
 
-void ShowRewardPopup(int amount) => Debug.Log($"Earned {amount} MVT!");
-void OnGameDone(int score, int duration) => Debug.Log($"Score: {score} in {duration}s");
-\`\`\`
+Replace the body of \`OnBegin()\` with your actual gameplay. Call \`CompleteMission(score)\` (or \`FailMission(reason)\`) when the player finishes. The host handles the rest \u2014 session tracking, MVT rewards, returning to the M-UNI home screen.
 
-## Deploy
+For configurable missions (quiz questions, level layouts, etc.), create a \`MissionConfig\` subclass and ship it as an asset alongside your scene.
 
-\`\`\`bash
-myvillage deploy --platform ios        # Upload iOS bundles
-myvillage deploy --platform android    # Upload Android bundles
-myvillage deploy --platform webgl      # Upload WebGL build
-myvillage status                       # Check review status
-\`\`\`
+## Reference
 
-After deploying, an admin will review your game, set MVT rewards, and publish it.
-Published games appear automatically in the Izi Graham mobile app or M-UNI web platform.
+- SDK source: https://github.com/MyVillage-Project-Technologies/myvillage-gamekit
+- Developer docs: https://myvillageproject.ai/developers
+- CLI commands: \`myvillage --help\`
 `;
 }
 
@@ -699,11 +366,16 @@ function generatePackageJson(name, description, slug, type, ageGroup) {
 }
 
 function generateViteConfig() {
+  // base: './' makes the built HTML use relative asset URLs (e.g. ./assets/main.js
+  // instead of /assets/main.js). The MyVillage host serves games at
+  // /api/v1/games/game-files/<slug>/, and relative URLs let the browser resolve
+  // bundled assets correctly under that path.
   return `import { defineConfig } from 'vite';
 
 export default defineConfig({
   root: '.',
   publicDir: 'public',
+  base: './',
   build: {
     outDir: 'dist',
     assetsDir: 'assets',