OASIS Learn/Module 12
Intermediate ⏱ 35 min WEB5

Missions & Quests

Missions are the structured goal units of the OASIS — each with objectives, completion conditions, karma rewards and optional NFT drops. Quests are the narrative arcs that chain missions together. Both work cross-game: an objective completed in OQuake can advance a mission in Our World.

What you'll build

  • Create a mission with multiple objectives and a karma reward
  • Track objective completion and auto-award karma on mission finish
  • Chain missions into a multi-stage quest
  • Query a player's active and completed quests
  • Use the STARAPIClient C interface for cross-game quest hooks (ODOOM / OQuake)
📦
API references

Missions-API.md ↗ · Quests-API.md ↗ · npm: @oasisomniverse/web5-api ↗

Creating a Mission

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

const { result: mission } = await star.missions.createMission({
  name:        'Retrieve the Crimson Key',
  description: 'Find the red key hidden in the ruined citadel and return it to the armoury.',
  objectives: [
    { name: 'Enter the citadel',    karmaReward: 10 },
    { name: 'Locate the red key',   karmaReward: 25 },
    { name: 'Survive the guardian',  karmaReward: 50 },
    { name: 'Return to armoury',     karmaReward: 15 },
  ],
  completionKarmaReward: 200,
  nftRewardId: 'crimson-key-nft-id',   // optional — mint NFT on completion
  expiresAt:   '2027-01-01T00:00:00Z',
});

console.log('Mission created:', mission.id);

Completing Objectives

Call completeObjective from your game or app when the player meets a condition. Karma is awarded automatically and the mission status updates.

complete-objective.js
// Player entered the citadel — complete objective index 0
const { result } = await star.missions.completeObjective({
  missionId:   mission.id,
  objectiveIndex: 0,
  avatarId:    currentAvatarId,
});

console.log('Progress:', result.completedObjectives, '/', result.totalObjectives);
console.log('Karma awarded:', result.karmaAwarded);
console.log('Mission complete:', result.missionComplete);

if (result.missionComplete) {
  console.log('🎉 NFT minted:', result.nftMintedId);
}

Building a Quest

A Quest chains multiple missions in order. Players must complete each mission before the next unlocks.

create-quest.js
const { result: quest } = await star.quests.createQuest({
  name:        'The Key Hunters Trilogy',
  description: 'Three missions across three worlds — ODOOM, OQuake and Our World.',
  missions: [
    { missionId: crimsonKeyMissionId,  order: 1 },
    { missionId: blueKeyMissionId,     order: 2 },
    { missionId: goldenKeyMissionId,   order: 3 },
  ],
  completionKarmaReward: 1000,
  completionNftRewardId: 'master-key-nft-id',
});

console.log('Quest created:', quest.id);

Querying Player Progress

quest-progress.js
// Active quests for this avatar
const { result: active } = await star.quests.getActiveQuests({ avatarId });
const { result: completed } = await star.quests.getCompletedQuests({ avatarId });

console.log('Active:', active.length, 'Completed:', completed.length);

for (const q of active) {
  console.log(`  ${q.name}  progress=${q.completedMissions}/${q.totalMissions}`);
}

Cross-Game Quests via OGLib + STARAPIClient (C/C++)

For native games like ODOOM and OQuake, OGLib provides the shared C helper layer (config, session, beamin/beamout) that sits on top of the STARAPIClient C ABI. Your game code stays lean — OGLib handles the boilerplate, and you call star_api_* only for game-specific events:

c
// One-time setup — OGLib handles config loading and session restore
#define OGLIB_SESSION_IMPL
#define OGLIB_CONFIG_IMPL
#define OGLIB_BEAMIN_IMPL
#include "oglib.h"
#include "star_api.h"

// Game code — check cross-game inventory and complete quest objective
bool has_key = star_api_has_item("crimson_key");
star_api_complete_objective(quest_id, objective_index, avatar_id);
💡
Cross-game quest chains in the wild

The Key Hunters Trilogy quest that spans ODOOM → OQuake → Our World is the flagship cross-game demo. See the ODOOM and OQuake case studies for step-by-step integration guides.

Next steps