Build on the live match.

Quick start

A working app before your first registration.

Start with a complete dashboard and demo match. No account, Warcraft III installation, or desktop client required.

npx --yes --package=github:W3Booster/app-starter w3booster-create my-app
cd my-app
npm install
npm run dev

Open http://localhost:5173/. You should see two players and a running game clock. The starter includes complete rendering, error states, a transparent overlay, and demo scenarios. Follow the first-app tutorial to connect real data.

Add the SDK to an existing application

Create a private app in W3Booster first, then run these commands from your project directory. The following integration sketch assumes your own rendering functions.

npm install @w3booster/sdk
npx w3booster-settings init app_your_id --endpoint https://api.w3booster.com

import { w3boosterApp } from './w3booster.generated';

const runtime = w3boosterApp.createRuntime({ retry: true });

runtime.lifecycle.subscribe(snapshot => {
  renderConnection(snapshot.status, snapshot.error);
  renderMatch(snapshot.state, snapshot.settings);
  renderHostActions(snapshot.host);
}, { signal: runtime.signal });

await runtime.start();

// Component or page teardown:
await runtime.stop();

runtime.start() resolves after the current connection has synchronized state. runtime.stop() aborts runtime.signal and removes subscriptions scoped to that lifetime. The checked-in binding carries the exact client ID, scopes, settings schema, defaults, and revision; application code does not choose a WebSocket, carry credentials, apply patches, or implement reconnection.

Develop without W3Booster

Demo mode loads a representative fixture on demand and keeps demo code out of normal production startup.

const runtime = w3boosterApp.createRuntime({ demo: true });
await runtime.start();

Pass demo: { interval: 0, settings: { … } } for a deterministic fixture, or provide a complete demo state for focused UI tests.

Application model

One app. Up to three surfaces.

Every W3Booster app is a remotely hosted web application. Configure only the surfaces the product needs; hosting it yourself or through W3Booster does not change the SDK.

1. Enable Developer ModeUse the account menu in W3Booster, then open Apps → Developer.
2. Create a private appAdd its name, requested scopes, and at least one surface URL. W3Booster generates the public client ID. Localhost is allowed for development; deploy to HTTPS for publication.
3. Build and testUse demo data for UI work and an owner-only local session for real match data.
4. Invite testersPrivate invitation codes grant discovery; each tester still installs and enables the app.

Local development

Use real data without deploying.

Run Vite, Angular, or any web server on localhost. In your app’s developer page, choose Test locally and add the local URLs for the surfaces you are working on.

The session installs and enables the app only for its owner and temporarily replaces only the chosen surfaces. Published metadata and other users do not change. Return to the published version at any time.

// Normal application code stays environment-free.
const runtime = w3boosterApp.createRuntime();

// Only platform developers normally force a backend.
const local = w3boosterApp.createRuntime({
  backend: 'local'
});

Cloud is the default. W3Booster may add ?backend=local or ?backend=cloud to a platform launch, and the SDK honors it automatically. Use backend: 'auto' only when intentionally trying local before cloud.

Frontend lifecycle

Render connection, freshness, and state together.

runtime.lifecycle is the preferred database-bound UI boundary. Its snapshot atomically contains the client, status, state, isSynchronized, resolved settings, host capabilities, and the current connection error. It publishes immediately and after every transition.

const runtime = w3boosterApp.createRuntime({ retry: true });

runtime.lifecycle.subscribe(snapshot => {
  render({
    status: snapshot.status,
    state: snapshot.state,
    fresh: snapshot.isSynchronized,
    settings: snapshot.settings,
    host: snapshot.host,
    error: snapshot.error,
    retry: snapshot.retry
  });
}, { signal: runtime.signal });

await runtime.start();

Automatic reconnect preserves hydrated state for visual continuity but sets isSynchronized to false until a fresh snapshot arrives. During initial retry, snapshot.retry exposes the attempt, configured limit, last transient error, and next delay so a UI can show progress without parsing error strings. State subscriptions and watchers are reevaluated for freshness-only transitions even when the immutable state identity is unchanged. State is recursively immutable and structurally shared, so unchanged branches preserve identity.

State and scopes

One hydrated, capability-aware match model.

The platform filters data before serialization. A scope expresses which branch an app may read; it is not a subscription tier. state.capabilities is the final runtime answer after the app’s granted scopes, account plan, and match context have been applied. Individual optional values can still be absent when the live source does not provide them.

runtime.client.state.subscribe(state => {
  if (!state) return;

  const resources = state.capabilities.includes('resources')
    ? state.players[0]?.resources
    : undefined;

  renderResources(resources);
});

Complete API data model

Everything W3Booster delivers.

This is the full hydrated MatchState<TSettings> exposed by @w3booster/sdk. The SDK validates it at runtime, freezes it recursively, and maintains it from snapshots and patches.

overlay:read is retired. OverlayRuntimeState remains a deprecated compatibility alias. Shared context is always delivered; Match Vision’s score belongs to its application data. The old matchScore() and matchScoreOrZero() selectors are deprecated compatibility helpers.

Events and selectors

Observe the view model you need.

Use state subscriptions for complete rendering, watch() for one derived value, and domain events for meaningful changes after the initial snapshot.

const client = runtime.client;
client.state.watch(
  state => state?.match.gameTime ?? null,
  seconds => drawClock(seconds),
  { signal: runtime.signal }
);

client.on('match.started', ({ match }) => showMatch(match), { signal: runtime.signal });
client.on('player.resources.changed', ({ player, resources }) => {
  updateEconomy(player.id, resources);
}, { signal: runtime.signal });
client.on('hero.inventory.changed', ({ player, inventory }) => {
  updateInventory(player.id, inventory);
}, { signal: runtime.signal });

client.subscribeMatchLifecycle(({ phase, initial, match, observedAt }) => {
  updateHistory({ phase, initial, match, observedAt });
}, { signal: runtime.signal, includeCurrentFinished: true });

The initial snapshot emits state.ready and state.changed. It does not synthesize match.started for a match that was already running. Use subscribeMatchLifecycle() when a feature needs that initial active match and later starts/ends through one exactly-once stream. By default an initially finished match is only a baseline; history and audit features can opt into one initial ended observation with includeCurrentFinished: true. Lifecycle observedAt is client observation time; prefer authoritative match.startedAt and match.endedAt when present.

match.result can arrive after the first finished snapshot and match.ended event. Observe state updates, keep missing outcomes unknown, and deduplicate persisted actions by match.id across hydration, reconnects, and app windows. The SDK does not maintain a session score. Read the result guide.

Pure selectors

import {
  broadcasterPlayer,
  groupPlayersByTeam,
  headToHeadPair,
  playerDisplayIdentity,
  playerResources,
  playerResourcesOrZero,
  gameContext,
  playerRelationship
} from '@w3booster/sdk/selectors';

const broadcaster = broadcasterPlayer(state.match, state.players);
const teams = groupPlayersByTeam(state.players);
const headToHead = headToHeadPair(state.players); // typed pair, or null
const identity = playerDisplayIdentity(broadcaster, {
  stripBattleTagDiscriminator: true
});
const context = gameContext(state); // no scope required; hudScale defaults to 1
const resources = playerResources(broadcaster); // undefined when unavailable
const displayResources = playerResourcesOrZero(broadcaster);

Selectors are framework-free, preserve immutable input identity where useful, and never mutate state. Team grouping accepts lightweight records with team: null; tuple and grouping helpers preserve input subtypes so applications do not need casts or local regrouping. Availability-preserving selectors return undefined; choose an explicit OrZero helper only when zero is the intended presentation fallback. The namespace also includes broadcaster-first teams, relationships, inventory, upgrades, and shared game context.

Standard-game data and assets

Import only the Warcraft knowledge you use.

Rules, icons, and cooldown metadata have separate entry points. This keeps lightweight apps small while preserving a combined objects namespace for compatibility.

import * as game from '@w3booster/sdk/standard-game';
import * as standardGameIcons from '@w3booster/sdk/standard-game/icons';
import * as cooldowns from '@w3booster/sdk/standard-game/cooldowns';

const assets = standardGameIcons.createAssetResolver();
const heroIcon = assets.hero(state.match, hero);
const countryFlag = assets.countryFlag(player.mainAccount?.country);
const cooldown = cooldowns.abilityCooldown(ability, state.match.gameTime);
const clock = game.formatGameTime(state.match.gameTime);
const progress = game.heroExperienceState(hero.experience);
const raceKey = game.raceInfo(player.race).localizationKey;
const teams = game.orderMatchTeams(state.players, state.match, { reverse: false });

The standard-game namespace covers locale-neutral race IDs and localization keys, modes, player colors, statistics selection, game-time formatting, day/night state, hero progression, health/mana ratios, upkeep, mode-aware presentation-team ordering, and presentation colors. Team ordering keeps the broadcaster first on player and team-observer surfaces, uses map position for 1v1 observer/replay surfaces, and preserves FFA sides. The launch-aware asset resolver binds Warcraft icons and country flags to one validated asset origin. Your app owns translated race copy plus sprite and CSS layout policy. Artwork is not bundled with npm.

Typed settings

Define settings once. Keep UI and types together.

Build the schema in W3Booster and let the client render consistent controls. The SDK can generate a checked-in TypeScript binding with the exact schema, defaults, scopes, client ID, and a managed application runtime.

npx w3booster-settings init app_your_id --endpoint https://api.w3booster.com
npm run w3booster:sync
npm run w3booster:check

Commit src/w3booster.generated.ts. This keeps editor types and offline builds deterministic while making schema changes visible in code review.

import { w3boosterApp } from './w3booster.generated';

const runtime = w3boosterApp.createRuntime({ retry: true });

runtime.lifecycle.subscribe(snapshot => {
  renderMatch(snapshot.state, { fresh: snapshot.isSynchronized });
  renderSettings(snapshot.settings);
  renderHostActions(snapshot.host);
}, { signal: runtime.signal });

await runtime.start();
await runtime.stop();

The managed runtime resolves partial user settings over database defaults and publishes settings atomically with state and host capabilities. It also sends the generated definition revision during connection; APPLICATION_DEFINITION_MISMATCH means the binding must be synchronized and the app redeployed. Generated client, runtime, snapshot, and connect-option aliases preserve typed additive overlay extensions. Lower-level tools remain available from @w3booster/sdk/settings.

Host actions

Ask the workspace. Await the result.

Embedded app surfaces can open or close windows, persist typed settings, report their height, and send supported host commands. Generic app storage keeps application data isolated; apps own their scoring and other feature logic. Every asynchronous action waits for a host acknowledgement.

import { canUseHostCapability } from '@w3booster/sdk';

client.host.lifecycle.subscribe(host => {
  setCompactEnabled(canUseHostCapability(host, 'window:open'));
});

await client.host.openWindow({
  path: '?view=compact',
  width: 520,
  height: 620
});

const saved = await client.host.setSetting(
  'observer.layout',
  'wide',
  { signal, timeout: 3000 }
);

Use host.can(capability) for imperative code or the reactive host lifecycle for UI. Capability discovery distinguishes pending, known, legacy, and unavailable hosts. Setting writes are serialized globally so overlapping parent and child paths preserve request order. Action cancellation raises AbortError; rejected execution raises HostActionError; missing or timed-out hosts raise ConnectionError.

Framework integration

Use the store your framework already understands.

The SDK has no frontend framework dependency. @w3booster/sdk/store creates stable derived stores and observer-style subscribables for Angular, RxJS, Vue, Svelte, or plain JavaScript; a small React subpath implements the complete useSyncExternalStore contract.

const status = createSelectorStore(
  runtime.lifecycle,
  snapshot => snapshot.status
);

status.subscribe(renderStatus, { signal });

const store = createReactStore(client.lifecycle, {
  getServerSnapshot: () => ({
    status: 'idle', state: null,
    isSynchronized: false, error: null, retry: null
  })
});

const snapshot = useSyncExternalStore(
  store.subscribe,
  store.getSnapshot,
  store.getServerSnapshot
);

const lifecycle = toSignal(
  createSubscribable(runtime.lifecycle),
  { initialValue: runtime.lifecycle.get() }
);

Errors and diagnostics

Separate startup failure from runtime issues.

Catch permanent startup errors around start(). Subscribe to structured issue events for recoverable connection, protocol, recorder, and listener problems that should not turn healthy match data into a failed UI.

import {
  classifyW3BoosterError,
  createClient
} from '@w3booster/sdk';

const client = createClient({ clientId: 'your_app_id' });

client.on('issue', issue => {
  console.warn(issue.source, issue.recoverable, issue.error);
});

try {
  await client.start();
} catch (error) {
  const info = classifyW3BoosterError(error);
  switch (info.kind) {
    case 'permission': showOpenFromW3Booster(); break;
    case 'connection':
      if (info.code === 'APPLICATION_DEFINITION_MISMATCH') showRedeployRequired();
      else showOffline(info.code);
      break;
    case 'abort': break;
    default: report(info.error);
  }
}

Publish

Private first. Reviewed before discovery.

1. Complete the store listingAdd a clear description, surfaces, screenshots, source or homepage links, and requested scopes.
2. Test every surfaceCheck application, stream, and in-game behavior; disabled states; reconnects; and missing optional data.
3. Request reviewW3Booster reviews the record, hosted behavior, scope use, and user experience.
4. Make it publicAfter approval, users can discover and install it from the App Store. Metadata edits do not require another review.

Installation and enabling are separate platform states. Disabling preserves the app in the user’s library; uninstalling removes the grant. Revocation closes affected streams immediately.

Package reference

Focused entry points, one compatibility policy.