OASIS Learn/Module 7
Advanced ⏱ 40 min

Metaverse & Game Development

The WEB5 STAR SDK gives you access to OASIS' spatial layer — the map, virtual worlds (Celestial Bodies), quests, missions, inventory items and the OGEngine game framework that powers Our World.

What you'll learn

  • The OASIS spatial data model: Celestial Bodies, Spaces, Zones
  • Create a virtual world and populate it with map points
  • Design quests and missions with objectives and rewards
  • Place GeoNFTs on the real-world map and in virtual spaces
  • Add inventory items and set up collection mechanics
  • Integrate with the OGEngine (Our World game engine)

The WEB5 STAR SDK

Game and metaverse features live in the WEB5 STAR API — a layer above WEB4 that adds spatial awareness, game mechanics and celestial body management. Install alongside the WEB4 SDK:

terminal
npm install @oasisomniverse/web4-api @oasisomniverse/web5-api
oasis-star.js
import { OASISClient } from '@oasisomniverse/web4-api';
import { STARClient } from '@oasisomniverse/web5-api';

export const oasis = new OASISClient({ persistSession: true });
export const star  = new STARClient({
  baseUrl: 'https://api.web5.oasisomniverse.one',
  oasisClient: oasis    // shares the same auth token
});

Celestial Bodies — Virtual Worlds

A Celestial Body is a virtual world — a planet, moon, space station, dungeon or any other navigable environment. Players travel to Celestial Bodies via the Our World map and can interact with their contents.

create-world.js
import { star } from './oasis-star.js';

const { avatarId } = oasis.auth.getSession();

// Create a new virtual world
const { result: world } = await star.celestialBodies.createPlanet({
  name:        'Aetheria',
  description: 'A floating archipelago world of ancient ruins and sky-whales.',
  createdByAvatarId: avatarId,

  // World properties
  size:        'Large',         // 'Tiny' | 'Small' | 'Medium' | 'Large' | 'Massive'
  biome:       'SkyIslands',
  atmosphere:  'Breathable',
  gravity:     'Low',

  // Map placement — where on the Our World map does this world's portal appear?
  mapLat:      51.5,
  mapLng:     -0.12,
  imageUrl:    'https://myapp.com/worlds/aetheria-thumb.jpg',
  glbModelUrl: 'https://myapp.com/worlds/aetheria.glb'   // 3D model
});

console.log('World ID:', world.id);
console.log('Map portal placed at:', world.mapLat, world.mapLng);

World hierarchy

TypeDescriptionAPI method
PlanetMain world — players' primary destinationstar.celestialBodies.createPlanet()
MoonSatellite world, orbiting a Planetstar.celestialBodies.createMoon()
SpaceStationOrbital hub — hub world or trading poststar.celestialBodies.createSpaceStation()
AsteroidSmall navigable body, often for mini-gamesstar.celestialBodies.createAsteroid()
GrandQuincunxRoot of the celestial hierarchy — the multiversePre-created by OASIS

Map Points — Anchoring to the Real World

Map points let you pin content — buildings, portals, NPCs, loot crates, events — to real-world GPS coordinates that appear on the Our World AR/map layer. This is what powers location-based gameplay.

map-points.js
import { oasis, star } from './oasis-star.js';

// Add a map point (e.g. a portal to Aetheria near the Eiffel Tower)
const { result: point } = await oasis.map.createMapPoint({
  title:           'Portal to Aetheria',
  description:     'Step through to reach the sky-island world.',
  lat:              48.8584,   // Eiffel Tower
  lng:              2.2945,
  type:            'Portal',   // 'Portal' | 'NPC' | 'LootCrate' | 'Event' | 'Building'
  linkedWorldId:   world.id,
  iconUrl:         'https://myapp.com/icons/portal.png',
  arModelUrl:      'https://myapp.com/ar/portal-gate.glb',
  activationRadius: 30        // metres — how close to activate
});

// Load all map points in a bounding box
const { result: nearby } = await oasis.map.getMapPointsInBounds({
  minLat: 48.84, maxLat: 48.87,
  minLng:  2.27, maxLng:  2.32
});

// Load map points for a specific world
const { result: worldPoints } = await oasis.map.getMapPointsForWorld({ worldId: world.id });

Quests & Missions

Quests are structured goals players complete to earn rewards. Missions are groups of quests that form a narrative arc. Both are first-class OASIS objects stored as typed Holons.

create-quest.js
import { star } from './oasis-star.js';

// Create a quest
const { result: quest } = await star.quests.createQuest({
  name:        'The Lost Sky Compass',
  description: 'Find the three fragments of the ancient Sky Compass to unlock the Storm Keep.',
  worldId:     world.id,
  difficulty:  'Medium',
  estimatedMinutes: 30,

  objectives: [
    { title: 'Find the Eastern Fragment',  type: 'CollectItem', itemId: 'compass-east'  },
    { title: 'Find the Western Fragment',  type: 'CollectItem', itemId: 'compass-west'  },
    { title: 'Find the Northern Fragment', type: 'CollectItem', itemId: 'compass-north' },
    { title: 'Return to Sky Cartographer', type: 'TalkToNPC',   npcId:  'sky-cart-001' }
  ],

  rewards: {
    karma:   'CompletingQuest',
    xp:      500,
    items:   [{ itemId: 'storm-keep-key', quantity: 1 }],
    nftMint: true   // automatically mint commemorative NFT on completion
  },

  createdByAvatarId: avatarId
});

// Group quests into a mission (narrative arc)
const { result: mission } = await star.missions.createMission({
  name:     'Secrets of Aetheria',
  worldId:  world.id,
  questIds: [quest.id],    // add more quests as you create them
  createdByAvatarId: avatarId
});

Tracking quest progress

javascript
// Start a quest for an avatar
await star.quests.startQuestForAvatar({ questId: quest.id, avatarId });

// Mark an objective complete
await star.quests.completeObjective({
  questId:     quest.id,
  objectiveId: quest.objectives[0].id,
  avatarId
});

// Complete the quest (triggers reward payout)
await star.quests.completeQuestForAvatar({ questId: quest.id, avatarId });

// Load all active quests for a player
const { result: active } = await star.quests.getActiveQuestsForAvatar({ avatarId });

Inventory Items

In-world objects players can pick up — keys, crafting materials, weapons, consumables. Unlike NFTs, inventory items don't require on-chain minting and can be stacked.

javascript
// Define an item type (do this once, at game setup)
const { result: itemType } = await star.inventoryItems.createItemType({
  id:          'compass-east',
  name:        'Eastern Compass Fragment',
  description: 'One piece of the ancient Sky Compass.',
  iconUrl:     'https://myapp.com/items/compass-east.png',
  glbModelUrl: 'https://myapp.com/items/compass-east.glb',
  stackable:   false,
  tradeable:   false,
  rarity:      'Uncommon'
});

// Give an item to a player (after they find it in-world)
await oasis.avatar.addItemToAvatarInventory({
  itemId:   itemType.id,
  name:     itemType.name,
  quantity: 1
});

Integrating with OGEngine

The OGEngine (Our World Game Engine) is the Unity/Unreal-backed 3D engine that powers the flagship Our World game. If you're building a Unity or Unreal game, use the OGEngine SDK to access all OASIS data natively in-engine.

🎮
OGEngine SDK

Available as a Unity package and Unreal plugin. Download from the Dev Portal under "SDKs & DevKits". The package exposes OASISManager MonoBehaviour / Actor component that wraps the full WEB4 + WEB5 API surface with coroutine-friendly async wrappers.

csharp (Unity)
using NextGenSoftware.OASIS.API.Core;
using NextGenSoftware.OASIS.STAR;

public class QuestManager : MonoBehaviour
{
    private async void Start()
    {
        // Login with saved credentials
        var loginResult = await OASISManager.Instance.Avatar.LoginAsync(
            email: PlayerPrefs.GetString("email"),
            password: SecureStorage.Get("password")
        );

        // Load active quests
        var quests = await OASISManager.Instance.Quests
            .GetActiveQuestsForAvatarAsync(loginResult.Result.Id);

        foreach (var quest in quests.Result)
            Debug.Log($"Active quest: {quest.Name}");
    }

    public async void OnItemCollected(string itemId)
    {
        // Mark objective complete in current active quest
        await OASISManager.Instance.Quests.CompleteObjectiveAsync(
            currentQuestId, itemId, currentAvatarId
        );
    }
}

GeoSpatial Tips for Game Designers

📍
Best practices for GeoNFT placement
  • Density matters — space GeoNFTs at least 100m apart in dense urban areas; 500m+ in rural settings to avoid clustering.
  • Safety first — never place collectible points inside private property, on busy roads, or in waterways. The OASIS moderation team reviews flag reports.
  • Accessibility — always provide a "virtual collect" option for users who cannot physically travel, activated by a karma payment or time gate.
  • Seasonality — use the activeFrom / activeTo fields on map points to run time-limited events without deleting and recreating them.
🌍
Real-world use case — museum interactive trail

The Natural History Museum placed GeoNFTs at each exhibit. Visitors scan a QR code at each exhibit to collect the species NFT. Collecting all 24 species unlocks a "Master Naturalist" badge NFT and a free book in the museum shop. Because the NFTs are OASIS-native, they also appear in the visitor's Our World avatar wallet — becoming a permanent, shareable trophy of their visit long after the day is over.

STAR / WEB5 API Quick Reference

← Previous
Your First OApp