OASIS Learn/Module 13
Intermediate ⏱ 30 min WEB5

Celestial Bodies & Spaces

Every virtual world in the OASIS Omniverse is a CelestialBody — a star, planet, moon or asteroid. CelestialSpaces are the containing regions: galaxies, solar systems and nebulae. Together they form the spatial index that lets players navigate the entire metaverse from a single map.

What you'll build

  • Create a planet that hosts your game world
  • Nest it inside a solar system (CelestialSpace)
  • Attach missions, GeoHotSpots and metadata to the planet
  • Query nearby bodies by galaxy / solar system
  • Let players "warp" between bodies using the OASIS map
📦
API references

CelestialBodies-API.md ↗ · CelestialSpaces-API.md ↗ · npm: @oasisomniverse/web5-api ↗

The Spatial Hierarchy

OASIS spatial hierarchy
Universe
 └─ Galaxy (CelestialSpace)
     └─ SolarSystem (CelestialSpace)
         ├─ Star (CelestialBody)
         ├─ Planet (CelestialBody)  ← your game world lives here
         │   └─ Moon (CelestialBody)
         └─ AsteroidBelt (CelestialSpace)

Create a Solar System

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

const { result: solarSystem } = await star.celestialSpaces.create({
  name:              'Andura System',
  description:       'A distant system with three inhabited worlds.',
  celestialSpaceType: 'SolarSystem',
  parentGalaxyId:    ourGalaxyId,
});

Create a Planet

create-planet.js
const { result: planet } = await star.celestialBodies.create({
  name:               'Nexara Prime',
  description:        'A volcanic world where the Crimson Key was forged.',
  celestialBodyType:  'Planet',
  parentSolarSystemId: solarSystem.id,
  thumbnailUrl:       'https://cdn.oasisomniverse.one/planets/nexara.jpg',
  gameEngineType:     'Unity',    // or 'Unreal', 'Godot', 'Custom'
  metadata: {
    atmosphere: 'toxic',
    gravity:    1.4,
    population: 0,
  },
});

console.log('Planet created:', planet.id);

Attach Missions & Hotspots

attach-content.js
// Link a mission to this planet
await star.celestialBodies.addMission({ bodyId: planet.id, missionId: crimsonKeyMissionId });

// Link a GeoHotSpot (spawn point) to the planet
await star.celestialBodies.addHotSpot({ bodyId: planet.id, hotSpotId: spawnPointId });

// Query all missions on a planet
const { result: missions } = await star.celestialBodies.getMissions({ bodyId: planet.id });
console.log('Missions on planet:', missions.length);

Navigating the Map

navigate.js
// Get all planets in a solar system
const { result: bodies } = await star.celestialBodies.getForSpace({
  celestialSpaceId: solarSystem.id,
  bodyType: 'Planet',
});

// Warp an avatar to a planet (sets their location in the OASIS map)
await star.avatar.warpTo({ avatarId, celestialBodyId: planet.id });
💡
Our World uses Earth as a CelestialBody

The Our World AR game maps real-world GPS coordinates onto the Earth CelestialBody. GeoNFTs dropped on Earth are discoverable in AR at those exact locations. See Module 14 for the GeoNFT layer.

Next steps