Cloud Library
Browse the public Vastopia cloud catalog from the Library tab, add assets as references, and share your own models, textures, audio, maps and more.
12 min read
What the cloud library is#
The cloud library is a public catalog of assets uploaded by Vastopia creators: 3D models, textures and sprites, audio, complete maps, GUI interfaces, item and NPC definitions, and animation bases. Every asset has a numeric cloud id and a content checksum, and everything in it is public.
It works in both directions:
- Pull. Browse the catalog inside the editor and add an asset to the open project. Models come in as references — the project records that it uses the asset, the bytes live once in a shared store on your machine, and publishing packs them into the build from there.
- Share. Assets you import into a project upload to the library automatically in the background. Larger things — a whole map, an interface, an item or NPC with its model, an animation base — are shared deliberately with a Share… button.
You browse without signing in. Uploading, sharing and the Creations view need you to be signed in to your Vastopia account in the editor (the Account button at the right of the top bar opens the profile dialog with Sign In).
Open the Library tab#
Click Library in the top bar. The page is headed Asset Library and has one toolbar:
| Control | What it does |
|---|---|
| Search assets… | Case-insensitive search on name and tags. It is scoped to wherever you are in the category tree, and debounced (about a third of a second after you stop typing). |
| tags, comma,separated | Only show assets carrying all of these tags. |
| Card size S / M / L | Card width in the grid. |
| Refresh | Re-fetch the catalog. |
| Import Asset | Import 3D models (GLB, GLTF, OBJ, FBX), images or audio from disk into the open project. Imports upload to the cloud automatically (see below). |
| Cloud queue button | Appears only while uploads are pending or failed, reading "N uploading…" or "N failed". Click it to open the Cloud Uploads dialog. |
Below the toolbar, the cloud section has three view tabs:
- Store — the whole public catalog, browsed by category.
- Recent — assets you recently added to any project from this machine, newest first. This list is kept in editor settings (up to 60 entries), so it follows the PC, not your account.
- Creations — everything you personally uploaded, with private folders to organize it.
Browse by category#
The Store opens at the three top-level groups as cards: 3D Assets, 2D and Misc. Click a group to see its subcategories; click a subcategory to reach the searchable, paginated grid. A breadcrumb above the cards (for example: Library › 3D Assets › Items) takes you back up. Pages hold 40 assets; use Prev / Next under the grid, where the label reads "1–40 of N".
Categories are well-known tags, not a fixed schema. An upload is filed by the tags it carries, and anything untagged still appears under its type's group.
| Group | Subcategory | What it lists | Refinement chips |
|---|---|---|---|
| 3D Assets | Maps | Complete terrains with their props included. | — |
| 3D Assets | Items | Ready-made item definitions and equipment models, tagged item. | Weapons, Helms, Body Armour, Leg Armour, Accessories, Misc |
| 3D Assets | Objects | Interactable objects from the Data Editor (object) and scenery props from the map palette (props). | Interactable, Props / Scenery |
| 3D Assets | NPCs | Ready-made NPC definitions and character models. | — |
| 2D | GUI Interfaces | Complete interfaces from the GUI editor. | — |
| 2D | GUI Templates | Reusable component parts saved from the GUI editor (tag template). | — |
| 2D | Sprites | Icons and images (tag sprite). | — |
| 2D | Item Icons | Item artwork uploaded when items are made from a PNG (tag item-icon). | — |
| 2D | Textures | Map terrain textures (tag terrain). | — |
| Misc | Audio | Sound effects and music. | SFX, Music |
| Misc | Animations | Animation bases — a skeleton with every clip attached, ready for NPCs. | — |
Each card shows a thumbnail, the asset's name, the creator's name, and a badge: either the cloud id or In Project when this project already holds that exact asset (same id and same checksum). Hovering shows the type, download size and tags.
Add an asset to the project#
Click a card to open its details popup. It shows a large thumbnail, the type and download size (for example "3D Model · Download: 2.4 MB"), tags, "Cloud asset #id · by creator", the uploader's description, and an Already in this project badge when applicable. The confirm button is the action for that asset type:
| Asset type | Button | What you get |
|---|---|---|
| Model | Create Item from Model, Create NPC, Create Object (placeable) or Just Add the Model | Chosen with the Import as dropdown; the default follows the asset's tags (an item-tagged model defaults to item, npcs/npc to NPC, object/props to object). The first three create a minimal definition and jump to it in the Data Editor. A Model folder row decides where the model files in the Models library: (Automatic), (Models root), an existing folder, or a new folder name. |
| Texture, sprite, audio | Add to Project | The file is imported into the matching project folder. A terrain texture set installs straight into the project's terrain texture library. |
| Map | Add Map to Project | Terrain, paint and props, with their models and texture sets. You pick a Map name (lowercased; a name already used by a map in this project blocks the install) and a Library folder. The popup lists the terrain textures the bundle includes. Files already in your project — same models, same texture sets — are kept; nothing is overwritten. |
| Interface / template | Add Interface / Add Template | You pick the scene's File name; a name that already exists blocks the install rather than renaming. |
| Item / NPC | Add Item to Game / Add NPC to Game | The definition is installed with a fresh local id, its icons written under that id, and its model pulled as a reference. The editor jumps to the new entry. |
| Animation base | Add Animation Base | You pick the Base ID (letters, numbers, _); an id already in this project's animations blocks the install because NPCs reference bases by id. |
Audio assets add a Preview button to the popup: the first press downloads and verifies the file into the cache (which the later add reuses), then it toggles between Preview and Stop.
While a pull runs the card button reads Downloading…. Adding an asset that is already in the project is a no-op that returns the existing entry, so you can never create a duplicate by clicking twice.
Models are references, not copies#
When you add a model from the cloud, no model file is written into your project. Instead:
- The editor downloads the GLB once into a shared store on your machine (
user://cloud_asset_cache/), verifies its checksum, and converts it to the self-contained.scnthe editor and client load. That conversion happens once per machine; the second project that adds the same model gets it instantly, with no download and no re-conversion. - The project's asset library gets an entry whose path is virtual —
assets/models/cloud_<id>_<name>/<id>.scn— and the project root gains acloud_assets.jsonmanifest listing every cloud asset it uses, with its id, checksum and the paths it stands for. - Every place that loads a model resolves that virtual path to the store copy. Map props keep the portable project-relative path in
props.bin, and publishing injects the bytes into the PCK from the store, so the game is unaffected. - On every project open, the editor checks the manifest and restores anything missing from the cloud (a new machine, a cleared cache, a project restored through cloud project sync). A toast reports "Restored N cloud asset file(s) from the cloud library." An asset whose checksum changed on the cloud is not restored. Rows whose entry you deleted from the project are pruned instead.
Images and audio behave differently: they are ordinary files in assets/sprites/ or assets/audio/, shared on disk with the store's verified copy where the file system allows it, and also recorded in the manifest so they can be restored.
Reference models also show up in the Assets editor with a cloud badge on their card, and their right-click menu shows the disabled row Cloud Asset (linked).
Share your assets#
Automatic uploads#
Every asset you import into a project is queued for upload, whichever route it came in by: Import Asset in the Library tab, the Assets editor, the Data Editor's create page, or a file drop. The import itself never waits on the network — the editor keeps a copy of the source bytes in a spool folder at the project root (.vastopia_upload/, which no build or export ever packs) and a background worker drains the queue: hash, upload, finalize, then stamp the project asset with its cloud id. Signed out or offline just means jobs stay queued; they resume when you sign in or reconnect.
What is uploaded automatically:
| Project asset | Cloud type | Formats | Cloud size cap |
|---|---|---|---|
| 3D model | model | .glb, .gltf (a .gltf is repacked into one self-contained GLB before upload; .fbx/.obj upload as the GLB they were converted to) | 256 MB |
| Sprite, texture | texture | .png, .jpg, .webp | 32 MB |
| Sound effect, music | audio | .ogg, .wav, .mp3 | 64 MB |
UI scenes, skeletons and other asset types never upload. The editor also stops at 200 MB regardless of type and keeps such a file local-only. A sprite with no tags is tagged sprite; untagged audio is tagged music when it was imported as music and sfx when it was imported as a sound effect. The cloud stores blobs by content, so re-uploading identical bytes skips the transfer and still records a new listing under your account.
The Cloud Uploads dialog (the cloud queue button in the Library toolbar) lists each job as Queued, Uploading… or a failure with its error, each failure with a Retry button. When nothing is pending it reads "Nothing waiting — every asset in this project that can be uploaded is in the cloud." Its Sync existing assets to cloud button uploads everything in the project that is not on the cloud yet; models imported before the cloud library existed are skipped, because their original GLB was replaced by the converted .scn at import and the .scn is never uploaded.
You can also upload by hand from the Assets editor: right-click an asset for Upload to Cloud (or Retry Cloud Upload; an asset already uploaded shows On Cloud disabled), or select several and choose Upload N items to Cloud. Terrain textures get the same Upload to Cloud row in the Terrain Textures category.
Categorizing what you upload#
Tags decide where an upload appears in the Store. The Data Editor's model import screen has a Category field — None, Prop / Scenery, Interactable Object, NPC / Character or Item (equipment) — stored as a tag. Saving an item stamps its model with the equipment-slot bucket (item-weapon, item-helm, item-body, item-legs, item-accessory, or item-misc for items with no slot), so it lands under the matching Items chip; the object editor stamps object. An asset can carry at most 20 tags. You can edit the name, description and tags of anything you uploaded later, from the dashboard (see below).
Share a bundle#
The bigger things are shared explicitly. Open the relevant Store subcategory and use the share button in its chip row:
| Where | Button | What travels | What stays behind | Cap |
|---|---|---|---|---|
| Maps (also the Map Editor's Map Library right-click menu, Share to Cloud) | Share a Map… | The map directory with its terrain, paint and walkability data, the prop models its props.bin references, and the terrain texture sets its scene uses. The map's saved thumbnail becomes the card. Its terrain textures are also published as separate texture assets and linked to the map. | NPC and object spawns — their ids are project-local. | 512 MB |
| GUI Interfaces / GUI Templates | Share an Interface… / Share a Template… | The scene, nodes and all, plus any project images it references. | Editor-only resources. | 32 MB |
| Items / NPCs | Share an Item… / Share an NPC… | The client and server definition rows and item icons. The 3D model is not in the bundle — it rides as a link to its own cloud asset. | Scripts, dialogue options, animation links, skill requirements and drop tables. | 8 MB |
| Animations | Share an Animation Base… | The skeleton scene and every clip, self-contained. | The preview mesh. | 64 MB |
A map can only be shared after it has been saved in the Map Editor, because the server-side walkability export is generated on save; sharing an unsaved map is refused with "Save … in the Map Editor first". A map shared again from the Map Library offers to replace the earlier listing: the new asset publishes first, and only then is the old one deleted, so a failed share never removes the existing one.
Sharing an item or NPC is refused while its model is not on the cloud yet: "The model isn't in the cloud yet — wait for its upload to finish, then share again." A legacy model whose original GLB is gone can never upload, so such a definition cannot be shared.
Creations and folders#
The Creations view lists everything you have uploaded. Folders are yours alone: they organize your own uploads and never change what the public Store shows.
- Click New Folder to create one at the current level. A breadcrumb shows where you are; folder tiles appear above the asset grid.
- Drag an asset card onto a folder tile or a breadcrumb crumb to move it there. Cards in this view open their details on release, so a press can become a drag.
- Right-click a folder: Open, New Subfolder…, Rename…, Move to…, Delete Folder. Deleting a folder moves its contents up to the parent; nothing inside is deleted.
- Right-click an asset: Details…, Move to Folder…, Move out to Parent Folder. The details popup of your own upload also carries Move to Folder….
- A typed search in Creations ignores the current folder and searches all your uploads.
Folder names can be up to 80 characters; sibling names must differ (case-insensitively); trees go 8 levels deep; you can have up to 500 folders.
The same uploads and folders are on the web at Creations in the Creator Dashboard (/dashboard/creations): search all uploads, filter by type, drag between folders, and open an upload to edit its Name, Description, Tags and Folder, or Delete upload to remove it from the cloud library. Edits made on the website show up in the editor's Creations view on its next refresh.
AI asset requests#
When an AI agent working through MCP needs art it cannot make — a model, sprite or audio clip — it records a request in the project's asset_requests.json. Pending requests appear at the top of the Library tab under AI Asset Requests with the agent's brief (name, type, description and what it is for). Click Import for this to pick a file; it is imported under the requested name and type, and the request closes. Dismiss closes a request without importing. The section is hidden entirely when nothing is pending.
With AI (MCP)#
browse_cloud_assets— search the public catalog (query,typeofmodel/texture/audio, tags, paging) and see which results are already in the project. No credentials needed.pull_cloud_asset— add a cloud asset by id, checksum-verified; for models,make_prop: truealso creates a placeable object definition with its tile footprint measured from the model's real size. Idempotent.request_asset,list_asset_requests,close_asset_request— record, list and close the asset requests surfaced in the Library tab.