feat(onboarding): tour of the UI for first-time users

fission/biome.json

@@ -287,6 +287,15 @@
       "linter": {
         "enabled": false
       }
+    },
+    {
+      "includes": ["src/systems/multiplayer/bindings/**/*"],
+      "formatter": {
+        "enabled": false
+      },
+      "linter": {
+        "enabled": false
+      }
     }
   ],
   "assist": {

fission/manifest.d.ts

@@ -1 +1,2 @@
-export type ManifestFileType = Record<"robots" | "private" | "fields", { filename: string; hash: string }[]>
+export type ManifestFileEntry = { filename: string; hash: string; year?: number; thumbnail?: string }
+export type ManifestFileType = Record<"robots" | "private" | "fields", ManifestFileEntry[]>

fission/src/Synthesis.tsx

@@ -20,6 +20,8 @@ import { StateProvider } from "./ui/StateProvider.tsx"
 import { ThemeProvider } from "./ui/ThemeProvider.tsx"
 import { UIProvider } from "./ui/UIProvider.tsx"
 import CommandPalette from "@/ui/components/CommandPalette.tsx"
+import { TourProvider } from "./ui/tour/TourProvider.tsx"
+import TourOverlay from "./ui/tour/TourOverlay.tsx"
 import SessionStorage, { applyAutoToast } from "@/util/SessionStorage.ts"
 import { globalOpenModal } from "@/components/GlobalUIControls.ts"
 import { startMultiplayerWorld } from "@/ui/helpers/StartMultiplayerWorld.ts"
@@ -100,23 +102,26 @@ const Synthesis = () => {
                 >
                     <StateProvider>
                         <UIProvider>
-                            <Scene useStats={import.meta.env.DEV} key="scene-in-toast-provider" />
-                            <TouchControls />
-                            <SceneOverlay />
-                            <ContextMenu />
-                            <MainHUD key={"main-hud"} />
-                            <UIRenderer />
-                            <CommandPalette />
-                            <ProgressNotifications key={"progress-notifications"} />
-                            <Stack direction={"column"} gap={1} position={"absolute"} bottom={0} left={0}>
-                                <DragModeIndicator />
-                                <MultiplayerHUD />
-                            </Stack>
-                            <PortraitOverlay />
+                            <TourProvider>
+                                <Scene useStats={import.meta.env.DEV} key="scene-in-toast-provider" />
+                                <TouchControls />
+                                <SceneOverlay />
+                                <ContextMenu />
+                                <MainHUD key={"main-hud"} />
+                                <UIRenderer />
+                                <CommandPalette />
+                                <ProgressNotifications key={"progress-notifications"} />
+                                <Stack direction={"column"} gap={1} position={"absolute"} bottom={0} left={0}>
+                                    <DragModeIndicator />
+                                    <MultiplayerHUD />
+                                </Stack>
+                                <PortraitOverlay />
+                                <TourOverlay />
 
-                            {!consentPopupDisable && (
-                                <AnalyticsConsent onClose={onDisableConsent} onConsent={onConsent} />
-                            )}
+                                {!consentPopupDisable && (
+                                    <AnalyticsConsent onClose={onDisableConsent} onConsent={onConsent} />
+                                )}
+                            </TourProvider>
                         </UIProvider>
                     </StateProvider>
                 </SnackbarProvider>

fission/src/mirabuf/DefaultAssetLoader.ts

@@ -2,7 +2,10 @@ import { type MirabufCacheInfo, MiraType } from "@/mirabuf/MirabufLoader.ts"
 import type { ManifestFileType } from "../../manifest.d.ts"
 import { API_URL } from "@/util/Consts.ts"
 
-export type DefaultAssetInfo = Required<Pick<MirabufCacheInfo, "hash" | "remotePath" | "miraType" | "name">>
+export type DefaultAssetInfo = Required<Pick<MirabufCacheInfo, "hash" | "remotePath" | "miraType" | "name">> & {
+    year?: number
+    thumbnail?: string
+}
 
 class DefaultAssetLoader {
     private static _assets: DefaultAssetInfo[] = []
@@ -34,6 +37,8 @@ class DefaultAssetLoader {
                     hash: obj.hash,
                     miraType,
                     name: obj.filename,
+                    year: obj.year,
+                    thumbnail: obj.thumbnail ? `${baseUrl}/${dir}/${obj.thumbnail}` : undefined,
                 })
             })
         })

fission/src/mirabuf/MiraType.ts

@@ -0,0 +1,14 @@
+/**
+ * Kind of Mirabuf assembly.
+ *
+ * Kept in its own leaf module: `MirabufLoader` initializes its storage backend with a
+ * top-level `await`, so importing this enum from there makes the importer wait on that
+ * async module. Modules that need only the enum at evaluation time (e.g. the tour step
+ * table) would otherwise observe it as `undefined` when an import cycle is involved.
+ *
+ * The numeric values are persisted in the localStorage asset cache - do not renumber.
+ */
+export enum MiraType {
+    ROBOT = 1,
+    FIELD,
+}

fission/src/mirabuf/MirabufLoader.ts

@@ -1,17 +1,12 @@
 import { type Data, downloadData } from "@/aps/APSDataManagement"
-import { globalAddToast, globalOpenPanel } from "@/components/GlobalUIControls"
+import { globalAddToast } from "@/components/GlobalUIControls"
 import { mirabuf } from "@/proto/mirabuf"
 import World from "@/systems/World"
 import { type MirabufStorageBackend, initStorageBackend } from "@/mirabuf/MirabufStorageBackend"
+import { MiraType } from "@/mirabuf/MiraType"
 import { hashBuffer, unzipMira } from "@/util/Utility.ts"
-import InitialConfigPanel from "@/panels/configuring/initial-config/InitialConfigPanel.tsx"
-import { PAUSE_REF_ASSEMBLY_SPAWNING } from "@/systems/physics/PhysicsTypes.ts"
-import { createMirabuf } from "@/mirabuf/MirabufSceneObject.ts"
-import { getTargetControls } from "@/systems/scene/CameraControls.ts"
-import { ProgressHandle } from "@/components/ProgressNotificationData.ts"
-import type { EncodedAssembly, Message } from "@/systems/multiplayer/MultiplayerTypes"
-import { consolePrefixer } from "console-prefixer"
 import { detectAndTagWheels } from "@/systems/simulation/synthesis_brain/WheelDetector"
+import { consolePrefixer } from "console-prefixer"
 
 const console = consolePrefixer({
     defaultPrefix: {
@@ -28,7 +23,15 @@ export interface MirabufCacheInfo {
     name: string
     miraType: MiraType
     remotePath?: string
-    thumbnailStorageID?: string
+    year?: number
+    thumbnail?: string
+}
+
+export interface CacheRemoteOptions {
+    name?: string
+    expectedHash?: string
+    year?: number
+    thumbnail?: string
 }
 
 export interface MirabufRemoteInfo {
@@ -165,23 +168,23 @@ class MirabufCachingService {
      *
      * @param {string} fetchLocation Location of Mirabuf file.
      * @param {MiraType} miraType Type of Mirabuf Assembly.
-     * @param {string} name Optional display name for the cached file.
+     * @param {CacheRemoteOptions} options Optional metadata to store alongside the cached file.
      *
      * @returns {Promise<MirabufCacheInfo | undefined>} Promise with the result of the promise. Metadata on the mirabuf file if successful, undefined if not.
      */
     public static async cacheRemote(
         fetchLocation: string,
         miraType: MiraType,
-        name?: string,
-        expectedHash?: string
+        options: CacheRemoteOptions = {}
     ): Promise<MirabufCacheInfo | undefined> {
+        const { expectedHash, year, thumbnail } = options
         try {
             // grab file remote
             const resp = await fetch(encodeURI(fetchLocation), import.meta.env.DEV ? { cache: "no-store" } : undefined)
             if (!resp.ok) throw new Error(`${resp.status} ${resp.statusText}`)
 
             const miraBuff = await resp.arrayBuffer()
-            name ??= this.assemblyFromBuffer(miraBuff).info?.name ?? fetchLocation
+            const name = options.name ?? this.assemblyFromBuffer(miraBuff).info?.name ?? fetchLocation
 
             World.analyticsSystem?.event("Remote Download", {
                 assemblyName: name,
@@ -195,6 +198,8 @@ class MirabufCachingService {
                     miraType,
                     name,
                     remotePath: fetchLocation,
+                    year,
+                    thumbnail,
                 },
                 expectedHash
             )
@@ -214,6 +219,8 @@ class MirabufCachingService {
                 hash: await hashBuffer(miraBuff),
                 miraType: miraType,
                 name: name,
+                year,
+                thumbnail,
             }
         } catch (e) {
             console.warn("Caching failed", e)
@@ -360,6 +367,10 @@ class MirabufCachingService {
         return this._cacheMap.getAll(miraType)
     }
 
+    public static has(hash: string): boolean {
+        return this._cacheMap.get(hash) != null
+    }
+
     /**
      * Removes a given Mirabuf item from the cache
      */
@@ -463,84 +474,6 @@ class MirabufCachingService {
     }
 }
 
-export enum MiraType {
-    ROBOT = 1,
-    FIELD,
-}
+export { MiraType }
 
 export default MirabufCachingService
-
-export async function spawnCachedMira(
-    info: MirabufCacheInfo,
-    progressHandle: ProgressHandle = new ProgressHandle(info.name)
-) {
-    // If spawning a field, then remove all other fields
-    if (info.miraType === MiraType.FIELD) {
-        if (World.multiplayerSystem != null && World.sceneRenderer.mirabufSceneObjects.getField() != null) {
-            globalAddToast("warning", "Cannot spawn a second field!")
-            progressHandle.fail("Cannot spawn a second field")
-            return
-        }
-        World.sceneRenderer.removeAllFields()
-    }
-
-    World.physicsSystem.holdPause(PAUSE_REF_ASSEMBLY_SPAWNING)
-    await MirabufCachingService.get(info.hash)
-        .then(async assembly => {
-            if (!assembly) {
-                progressHandle.fail()
-                console.error("Failed to spawn robot")
-
-                return
-            }
-
-            await createMirabuf(info.hash, assembly, progressHandle).then(async mirabufSceneObject => {
-                if (!mirabufSceneObject) {
-                    progressHandle.fail("No object!")
-                    return
-                }
-
-                World.sceneRenderer.registerSceneObject(mirabufSceneObject)
-
-                const targetControls = getTargetControls()
-
-                if (World.multiplayerSystem != null) {
-                    const encodedAssembly =
-                        mirabufSceneObject.miraType !== MiraType.FIELD
-                            ? (mirabuf.Assembly.encode(assembly).finish() as EncodedAssembly)
-                            : undefined
-
-                    const message: Message = {
-                        type: "newObject",
-                        timestamp: Date.now(),
-                        data: {
-                            sceneObjectId: mirabufSceneObject.id,
-                            assembly: encodedAssembly,
-                            assemblyHash: info.hash,
-                            miraType: info.miraType,
-                            initialPreferences: mirabufSceneObject.getPreferenceData(),
-                        },
-                    }
-                    World.multiplayerSystem?.broadcast(message)
-                    World.multiplayerSystem?.registerOwnSceneObject(mirabufSceneObject.id)
-                }
-
-                if (targetControls && (info.miraType === MiraType.ROBOT || !targetControls.focusProvider)) {
-                    targetControls.focusProvider = mirabufSceneObject
-                }
-
-                progressHandle.done()
-                World.physicsSystem.deactivateGamepieces()
-                if (mirabufSceneObject.miraType == MiraType.ROBOT) {
-                    globalOpenPanel(InitialConfigPanel, undefined)
-                }
-            })
-        })
-        .catch(e => {
-            console.error(e)
-            progressHandle.fail()
-        })
-        .finally(() => {
-            setTimeout(() => World.physicsSystem.releasePause(PAUSE_REF_ASSEMBLY_SPAWNING), 500)
-        })
-}

fission/src/mirabuf/MirabufSceneObject.ts

@@ -103,6 +103,8 @@ class MirabufSceneObject extends SceneObject implements ContextSupplier {
     public readonly mirabufInstance: MirabufInstance
     public readonly mechanism: Mechanism
 
+    public assemblyHash?: string
+
     private _brain: Brain | undefined
     public alliance: Alliance | undefined
     public station: Station | undefined
@@ -1443,9 +1445,10 @@ export async function createMirabuf(
 ): Promise<MirabufSceneObject | undefined> {
     const parser = new MirabufParser(assembly, progressHandle)
 
-    if (!parser.assembly.info?.GUID?.match(/\w{8}-\w{4}-\w{4}-\w{4}-\w{12}/)) {
-        await migrateUUID(parser, hash)
-    }
+    const resolvedHash = parser.assembly.info?.GUID?.match(/\w{8}-\w{4}-\w{4}-\w{4}-\w{12}/)
+        ? hash
+        : ((await migrateUUID(parser, hash)) ?? hash)
+
     if (parser.maxErrorSeverity >= ParseErrorSeverity.UNIMPORTABLE) {
         console.error(`Assembly Parser produced significant errors for '${assembly.info!.name!}'`)
         return
@@ -1456,10 +1459,12 @@ export async function createMirabuf(
     progressHandle?.update("Created Mirabuf Instance", URDFImportProgressBar.MIRABUF_INSTANCE)
     await yieldToMain()
 
-    return new MirabufSceneObject(mirabufInstance, progressHandle, multiplayerOwnerId)
+    const sceneObject = new MirabufSceneObject(mirabufInstance, progressHandle, multiplayerOwnerId)
+    sceneObject.assemblyHash = MirabufCachingService.has(resolvedHash) ? resolvedHash : undefined
+    return sceneObject
 }
 
-async function migrateUUID(parser: MirabufParser, hash: string) {
+async function migrateUUID(parser: MirabufParser, hash: string): Promise<string | undefined> {
     parser.assembly.info ??= {}
     const newGUID = uuidV4({ random: hexStringToUint8Array(hash).slice(0, 16) }) // using deterministic random to prevent the same model from being assigned different uuids after being imported multiple times. Once initially set, uuid will be persistent across hash changes
     console.warn("Migrating UUID", parser.assembly.info.GUID, "->", newGUID)
@@ -1477,6 +1482,7 @@ async function migrateUUID(parser: MirabufParser, hash: string) {
     if (cacheInfo == null) {
         globalAddToast("warning", "Migration Error", "Importing failed to save")
     }
+    return cacheInfo?.hash
 }
 /**
  * Body association to a rigid node with a given mirabuf scene object.